@morshoto/framekit 0.1.14 → 0.1.16

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 (30) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +28 -0
  2. package/dist-package/adapters/final-cut/typescript/src/canonical.js +144 -35
  3. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
  4. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
  5. package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
  6. package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
  7. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
  8. package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
  9. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
  10. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +75 -3
  11. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
  12. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +443 -0
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
  14. package/dist-package/adapters/headless/typescript/src/index.js +3 -0
  15. package/dist-package/apps/mcp-server/src/headless-projects.js +139 -0
  16. package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
  17. package/dist-package/apps/mcp-server/src/main.js +22 -1
  18. package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
  19. package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
  20. package/dist-package/apps/mcp-server/src/routing.js +134 -5
  21. package/dist-package/apps/mcp-server/src/server.js +214 -31
  22. package/dist-package/packages/runtime/src/application/local-media.js +157 -0
  23. package/dist-package/packages/runtime/src/application/project-store.js +234 -0
  24. package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
  25. package/dist-package/packages/runtime/src/index.js +6 -0
  26. package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
  27. package/dist-package/packages/runtime/src/render/render-contract.js +143 -0
  28. package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
  29. package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
  30. package/package.json +2 -1
@@ -1,3 +1,26 @@
1
+ export const HEADLESS_TIMELINE_EDIT_TYPES = [
2
+ "insert-occurrence",
3
+ "rename-occurrence",
4
+ "trim-occurrence",
5
+ "move-occurrence",
6
+ "split-occurrence",
7
+ "set-gain",
8
+ "set-transform",
9
+ "remove-occurrence",
10
+ "add-marker",
11
+ "add-title",
12
+ "remove-title",
13
+ "add-transition",
14
+ "remove-transition",
15
+ ];
16
+ export const EDITING_ROUTE_EDIT_TYPES = [
17
+ ...HEADLESS_TIMELINE_EDIT_TYPES,
18
+ "rename-clip",
19
+ "trim-clip",
20
+ "reduce-noise",
21
+ "set-color-correction",
22
+ "ripple-delete",
23
+ ];
1
24
  export const EDITOR_FIRST_WORKFLOW = [
2
25
  "connection.status",
3
26
  "editor.inspect",
@@ -10,6 +33,14 @@ export const EDITOR_FIRST_WORKFLOW = [
10
33
  "edit.diff",
11
34
  "edit.verify",
12
35
  ];
36
+ export const HEADLESS_FIRST_WORKFLOW = [
37
+ "connection.status",
38
+ "editing.route",
39
+ "headless.project.open",
40
+ "headless.edit.preview",
41
+ "headless.edit.execute",
42
+ "headless.project.inspect",
43
+ ];
13
44
  export const BACKGROUND_LIBRARY_WORKFLOW = [
14
45
  "connection.status",
15
46
  "editor.inspect",
@@ -38,9 +69,20 @@ export const EDITOR_FIRST_MCP_INSTRUCTIONS = [
38
69
  "5. Resolve intent when needed, then preview before execute; never mutate on an unavailable capability.",
39
70
  "6. Observe the result, then use edit.diff and edit.verify to confirm the change.",
40
71
  "Background project and live metadata may use project.list and editor.live.inspect without canonical timeline proof.",
72
+ "For repeated agent readback, use the bound session or complete fast observation; force canonical resync for initial binding, stale/conflicted state, incomplete evidence, explicit canonical inspection, and final verification.",
41
73
  "For an explicit FCPXML artifact, select artifact.edit; its background workflow uses artifact.inspect, artifact.edit.preview, artifact.edit.execute, artifact.edit.diff, artifact.edit.verify, and artifact.edit.undo, and never claims to change the open Final Cut timeline.",
42
74
  "An external renderer is never an implicit substitute for a connected editor. Select fallback: external-renderer explicitly and report the structured reason returned by editing.route.",
43
75
  ].join("\n");
76
+ export const HEADLESS_FIRST_MCP_INSTRUCTIONS = [
77
+ "Framekit uses the headless Framekit-owned project as the default editing path.",
78
+ "1. Call connection.status only for diagnostics; Final Cut availability is not required for headless editing.",
79
+ "2. Call editing.route for the intended operation and follow the selected path and reason.",
80
+ "3. For a headless route, use headless.project.open or headless.project.inspect, then preview before execute.",
81
+ "4. Reopen and inspect the exact project revision before rendering; independently verify the render result.",
82
+ "5. Headed/native execution requires an explicit path: headed selection and the native operation tools; it is never an implicit fallback.",
83
+ "An unavailable headless capability returns structured evidence and does not launch or activate Final Cut.",
84
+ "An external renderer is never an implicit substitute. Select fallback: external-renderer explicitly and report the structured reason.",
85
+ ].join("\n");
44
86
  const operationRequirements = {
45
87
  "project.list": [backgroundLibraryRequirement()],
46
88
  "project.select": [editorRequirement("projectSelection", "native-ui")],
@@ -100,11 +142,14 @@ export function resolveEditingRoute(request, context) {
100
142
  const missingCapabilities = missingRequirements.map((requirement) => requirement.label);
101
143
  const editor = context.editor?.identity;
102
144
  const readiness = routingReadiness(context);
103
- const workflow = request.operation === "artifact.edit"
104
- ? BACKGROUND_ARTIFACT_WORKFLOW
105
- : request.operation === "project.list"
106
- ? BACKGROUND_LIBRARY_WORKFLOW
107
- : EDITOR_FIRST_WORKFLOW;
145
+ const headlessDefault = request.operation === "timeline.edit" && context.headless && request.path !== "headed";
146
+ const workflow = request.operation === "timeline.edit" && headlessDefault
147
+ ? HEADLESS_FIRST_WORKFLOW
148
+ : request.operation === "artifact.edit"
149
+ ? BACKGROUND_ARTIFACT_WORKFLOW
150
+ : request.operation === "project.list"
151
+ ? BACKGROUND_LIBRARY_WORKFLOW
152
+ : EDITOR_FIRST_WORKFLOW;
108
153
  if (request.fallback === "external-renderer") {
109
154
  const cause = externalFallbackCause(context, missingCapabilities);
110
155
  return {
@@ -124,6 +169,31 @@ export function resolveEditingRoute(request, context) {
124
169
  },
125
170
  };
126
171
  }
172
+ const headlessRequested = request.path === "headless";
173
+ if (headlessRequested || (headlessDefault && request.path !== "headed")) {
174
+ if (context.headless?.available && headlessSupportsRequest(request, context)) {
175
+ return {
176
+ operation: request.operation,
177
+ status: "headless-selected",
178
+ selectedPath: "headless",
179
+ requiredCapabilities: [headlessCapability(request)],
180
+ missingCapabilities: [],
181
+ provider: {
182
+ backend: context.headless.backend,
183
+ guarantee: context.headless.guarantee,
184
+ },
185
+ ...(editor ? { editor } : {}),
186
+ ...(readiness ? { readiness } : {}),
187
+ workflow: [...HEADLESS_FIRST_WORKFLOW],
188
+ reason: {
189
+ code: "HEADLESS_SELECTED",
190
+ message: "The Framekit-owned headless project is the default SSoT path; Final Cut will not be contacted.",
191
+ connectionState: context.connection.state,
192
+ },
193
+ };
194
+ }
195
+ return headlessUnavailableRoute(request, context, editor, readiness, workflow);
196
+ }
127
197
  const offlineArtifactEdit = (request.operation === "artifact.edit" || request.operation === "timeline.edit")
128
198
  && Boolean(context.editor?.capabilities.editor.timelineArtifactWrite
129
199
  && (context.editor.capabilities.families?.canonicalDocument.artifactWrite.available ?? true));
@@ -319,6 +389,65 @@ function selectedPath(operation, provider) {
319
389
  return "native";
320
390
  return "editor";
321
391
  }
392
+ function headlessUnavailableRoute(request, context, editor, readiness, workflow) {
393
+ const capability = headlessCapability(request);
394
+ return {
395
+ operation: request.operation,
396
+ status: "unavailable",
397
+ selectedPath: "none",
398
+ requiredCapabilities: [capability],
399
+ missingCapabilities: [capability],
400
+ ...(editor ? { editor } : {}),
401
+ ...(readiness ? { readiness } : {}),
402
+ workflow: [...workflow],
403
+ reason: {
404
+ code: "HEADLESS_UNAVAILABLE",
405
+ message: "The requested Framekit headless SSoT capability is unavailable; no headed or native fallback was selected.",
406
+ connectionState: context.connection.state,
407
+ unavailable: {
408
+ category: "background-api",
409
+ capability,
410
+ backend: context.headless?.backend ?? "framekit-headless-project",
411
+ guarantee: context.headless?.guarantee ?? "none",
412
+ message: context.headless
413
+ ? "the configured headless project service does not advertise this operation"
414
+ : "no headless project service is configured",
415
+ },
416
+ },
417
+ };
418
+ }
419
+ function headlessSupportsRequest(request, context) {
420
+ if (!context.headless)
421
+ return false;
422
+ if (request.operation !== "timeline.edit") {
423
+ return context.headless.supportedOperations.includes(request.operation);
424
+ }
425
+ // A bare timeline.edit request is intentionally not a headless capability:
426
+ // the legacy surface also contains operations that Timeline IR cannot apply.
427
+ const editType = canonicalHeadlessEditType(request.editType);
428
+ return editType !== undefined
429
+ && context.headless.supportedOperations.includes(`timeline.edit:${editType}`);
430
+ }
431
+ function headlessCapability(request) {
432
+ if (request.operation !== "timeline.edit")
433
+ return `headless.${request.operation}`;
434
+ const editType = canonicalHeadlessEditType(request.editType);
435
+ return request.editType
436
+ ? `headless.timeline.edit.${editType ?? request.editType}`
437
+ : "headless.timeline.edit";
438
+ }
439
+ function canonicalHeadlessEditType(editType) {
440
+ if (!editType)
441
+ return undefined;
442
+ switch (editType) {
443
+ case "rename-clip": return "rename-occurrence";
444
+ case "trim-clip": return "trim-occurrence";
445
+ default:
446
+ return HEADLESS_TIMELINE_EDIT_TYPES.includes(editType)
447
+ ? editType
448
+ : undefined;
449
+ }
450
+ }
322
451
  function selectedMessage(operation) {
323
452
  if (operation === "project.list" || operation === "editor.live.inspect") {
324
453
  return "The background observation provider satisfies the requested metadata fields; no canonical timeline proof is implied.";
@@ -2,12 +2,13 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
3
3
  import { resolve as resolvePath } from "node:path";
4
4
  import { z } from "zod";
5
- import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, } from "../../../packages/runtime/src/index.js";
5
+ import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, createTimelineIrFromProjectSnapshot, } from "../../../packages/runtime/src/index.js";
6
6
  import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
7
- import { BACKGROUND_ARTIFACT_WORKFLOW, EDITOR_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
7
+ import { BACKGROUND_ARTIFACT_WORKFLOW, EDITING_ROUTE_EDIT_TYPES, EDITOR_FIRST_MCP_INSTRUCTIONS, HEADLESS_TIMELINE_EDIT_TYPES, HEADLESS_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
8
8
  import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
9
9
  import { EditingSessionRepository } from "./headless-sessions.js";
10
10
  import { SessionMaterializationJobs, } from "./materialization-jobs.js";
11
+ import { chooseTimelineReadback } from "./readback-policy.js";
11
12
  const revisionValueSchema = z.object({
12
13
  id: z.string(),
13
14
  sequence: z.number().int().nonnegative(),
@@ -18,6 +19,11 @@ const contextTargetSchema = z.object({
18
19
  projectId: z.string().min(1),
19
20
  sequenceId: z.string().min(1),
20
21
  }).strict();
22
+ const timelineReadbackSchema = z.object({
23
+ sessionId: z.string().min(1).optional(),
24
+ requestedCanonical: z.boolean().optional().default(false),
25
+ finalVerification: z.boolean().optional().default(false),
26
+ }).strict();
21
27
  const contextCursorSchema = z.object({
22
28
  revision: revisionValueSchema,
23
29
  target: contextTargetSchema.optional(),
@@ -165,6 +171,7 @@ const editOperationSchema = z.discriminatedUnion("type", [
165
171
  rippleDeleteSchema,
166
172
  addMarkerSchema,
167
173
  ]);
174
+ const editingPathSchema = z.enum(["headless", "headed"]).optional();
168
175
  const verificationAssertionSchema = z.discriminatedUnion("type", [
169
176
  z.object({
170
177
  type: z.literal("audio-audibility"),
@@ -268,13 +275,14 @@ function createEditToolInputSchema(target = {}, baseRevision = revisionSchema) {
268
275
  ];
269
276
  return mcpDiscriminatedUnion(options);
270
277
  }
271
- const editToolInputSchema = createEditToolInputSchema();
278
+ const editToolInputSchema = createEditToolInputSchema({ path: editingPathSchema });
272
279
  const artifactEditToolInputSchema = createEditToolInputSchema({
273
280
  artifactPath: z.string().trim().min(1),
274
281
  }, revisionValueSchema);
275
282
  const editorTimelineEditToolInputSchema = createEditToolInputSchema({
276
283
  projectId: z.string().trim().min(1),
277
284
  sequenceId: z.string().trim().min(1),
285
+ path: editingPathSchema,
278
286
  }, revisionValueSchema);
279
287
  function exposeObjectRoot(schema) {
280
288
  if (!isRecord(schema) || !Array.isArray(schema.anyOf))
@@ -824,7 +832,7 @@ function frameResult(value) {
824
832
  }
825
833
  export function createMcpServer(runtime, options = {}) {
826
834
  runtime.registerBuiltinSkills();
827
- const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: EDITOR_FIRST_MCP_INSTRUCTIONS });
835
+ const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: options.headlessProjects ? HEADLESS_FIRST_MCP_INSTRUCTIONS : EDITOR_FIRST_MCP_INSTRUCTIONS });
828
836
  const nativeTransitionAssets = new Map();
829
837
  const sessions = options.sessionDirectory
830
838
  ? new EditingSessionRepository(options.sessionDirectory, options.sessionChangeSource)
@@ -842,6 +850,37 @@ export function createMcpServer(runtime, options = {}) {
842
850
  throw new Error("MATERIALIZATION_STORAGE_UNAVAILABLE: configure a materialization directory");
843
851
  return materializations;
844
852
  };
853
+ const requireHeadlessProjects = () => {
854
+ if (!options.headlessProjects)
855
+ throw new Error("HEADLESS_PROJECT_UNAVAILABLE: headless project storage is not configured");
856
+ return options.headlessProjects;
857
+ };
858
+ const prepareSessionReadback = async (sessionId, requestedCanonical, finalVerification) => {
859
+ const stored = await requireSessions().inspect(sessionId);
860
+ const decision = chooseTimelineReadback({
861
+ hasCanonicalBase: true,
862
+ requestedCanonical,
863
+ finalVerification,
864
+ sessionState: stored.document.state,
865
+ ...(stored.document.observation ? {
866
+ fastObservation: {
867
+ available: true,
868
+ coverageComplete: stored.document.observation.coverageComplete,
869
+ status: "possibly-stale",
870
+ },
871
+ } : {}),
872
+ });
873
+ return { stored, decision };
874
+ };
875
+ const canonicalResyncSession = async (sessionId, providerId) => {
876
+ if (providerId && providerId !== "final-cut") {
877
+ throw new Error(`SESSION_PROVIDER_MISMATCH: canonical Final Cut resync cannot replace provider ${providerId}`);
878
+ }
879
+ const snapshot = await runtime.inspectProject();
880
+ const timeline = createTimelineIrFromProjectSnapshot(snapshot, { id: "final-cut" });
881
+ const session = await requireSessions().reconcile(sessionId, { id: "final-cut" }, timeline);
882
+ return { snapshot, session };
883
+ };
845
884
  const sessionOperationSchema = z.array(z.unknown());
846
885
  server.registerTool("session.create", {
847
886
  description: "Create and atomically persist a provider-neutral editing session without mutating Final Cut.",
@@ -921,6 +960,10 @@ export function createMcpServer(runtime, options = {}) {
921
960
  description: "Resume a retryable persisted materialization job with its verified immutable artifact.",
922
961
  inputSchema: { jobId: z.string().min(1) },
923
962
  }, async ({ jobId }) => sessionResult(async () => requireMaterializations().retry(jobId)));
963
+ server.registerTool("session.materialize.resync", {
964
+ description: "Read the completed versioned handoff target and create a fresh editing-session baseline for continuation.",
965
+ inputSchema: { jobId: z.string().min(1), sessionId: z.string().min(1) },
966
+ }, async ({ jobId, sessionId }) => sessionResult(async () => requireMaterializations().resync(jobId, sessionId)));
924
967
  server.registerTool("connection.status", {
925
968
  description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
926
969
  inputSchema: {},
@@ -987,8 +1030,22 @@ export function createMcpServer(runtime, options = {}) {
987
1030
  }
988
1031
  });
989
1032
  server.registerTool("project.inspect", {
990
- description: "Read the current canonical project snapshot before editing.route selects a capability-checked path.",
991
- }, async () => {
1033
+ description: "Read a bound session baseline or perform an explicit canonical project resync before editing.route selects a capability-checked path.",
1034
+ inputSchema: timelineReadbackSchema,
1035
+ }, async ({ sessionId, requestedCanonical, finalVerification }) => {
1036
+ if (sessionId) {
1037
+ const { stored, decision } = await prepareSessionReadback(sessionId, requestedCanonical, finalVerification);
1038
+ if (decision.route === "session" || decision.route === "fast-observation") {
1039
+ return jsonResult({
1040
+ sessionId,
1041
+ readback: decision,
1042
+ session: stored.document,
1043
+ snapshot: stored.document.base,
1044
+ });
1045
+ }
1046
+ const resynced = await canonicalResyncSession(sessionId, stored.document.provider?.id);
1047
+ return jsonResult({ sessionId, readback: decision, ...resynced });
1048
+ }
992
1049
  const inspected = await inspectMcpEditor(runtime, options);
993
1050
  const capability = inspected.capabilities.families.canonicalDocument.read;
994
1051
  if (!capability.available) {
@@ -1037,6 +1094,77 @@ export function createMcpServer(runtime, options = {}) {
1037
1094
  return capabilityUnavailableErrorResult(error);
1038
1095
  }
1039
1096
  });
1097
+ server.registerTool("headless.project.create", {
1098
+ description: "Create and persist a Framekit-owned canonical project without contacting Final Cut Pro.",
1099
+ inputSchema: { timeline: z.unknown() },
1100
+ }, async ({ timeline }) => sessionResult(async () => requireHeadlessProjects().create(timeline)));
1101
+ server.registerTool("headless.project.list", {
1102
+ description: "List persisted Framekit-owned projects and their stable canonical revisions.",
1103
+ inputSchema: {},
1104
+ }, async () => sessionResult(() => requireHeadlessProjects().list()));
1105
+ server.registerTool("headless.project.open", {
1106
+ description: "Open a persisted Framekit-owned project and fail closed if registered media changed or is missing.",
1107
+ inputSchema: { projectId: z.string().min(1) },
1108
+ }, async ({ projectId }) => sessionResult(() => requireHeadlessProjects().open(projectId)));
1109
+ server.registerTool("headless.project.inspect", {
1110
+ description: "Inspect the current persisted Framekit Timeline IR and exact revision.",
1111
+ inputSchema: { projectId: z.string().min(1) },
1112
+ }, async ({ projectId }) => sessionResult(() => requireHeadlessProjects().inspect(projectId)));
1113
+ server.registerTool("headless.media.register", {
1114
+ description: "Register one local source file in the canonical Framekit project with digest and ffprobe metadata.",
1115
+ inputSchema: {
1116
+ projectId: z.string().min(1),
1117
+ sourcePath: z.string().min(1),
1118
+ expectedRevision: revisionValueSchema.optional(),
1119
+ },
1120
+ }, async ({ projectId, sourcePath, expectedRevision }) => sessionResult(() => requireHeadlessProjects().registerMedia(projectId, sourcePath, expectedRevision)));
1121
+ server.registerTool("headless.edit.preview", {
1122
+ description: "Preview supported Framekit Timeline IR edits without persisting or mutating the project.",
1123
+ inputSchema: {
1124
+ projectId: z.string().min(1),
1125
+ sequenceId: z.string().min(1),
1126
+ expectedRevision: revisionValueSchema,
1127
+ operations: z.array(z.unknown()),
1128
+ },
1129
+ }, async ({ projectId, sequenceId, expectedRevision, operations }) => sessionResult(() => requireHeadlessProjects().previewEdit(projectId, {
1130
+ schemaVersion: 1,
1131
+ expectedRevision,
1132
+ operations: operations,
1133
+ }, sequenceId)));
1134
+ server.registerTool("headless.edit.execute", {
1135
+ description: "Execute supported Framekit Timeline IR edits against the expected canonical revision and persist exactly one revision.",
1136
+ inputSchema: {
1137
+ projectId: z.string().min(1),
1138
+ sequenceId: z.string().min(1),
1139
+ expectedRevision: revisionValueSchema,
1140
+ operations: z.array(z.unknown()),
1141
+ },
1142
+ }, async ({ projectId, sequenceId, expectedRevision, operations }) => sessionResult(() => requireHeadlessProjects().executeEdit(projectId, {
1143
+ schemaVersion: 1,
1144
+ expectedRevision,
1145
+ operations: operations,
1146
+ }, sequenceId)));
1147
+ const headlessRenderParametersSchema = z.object({
1148
+ outputPath: z.string().min(1),
1149
+ format: z.enum(["mp4", "mov"]),
1150
+ width: z.number().int().positive(),
1151
+ height: z.number().int().positive(),
1152
+ frameRate: rationalTimeSchema,
1153
+ overwrite: z.boolean().optional(),
1154
+ }).strict();
1155
+ server.registerTool("headless.render", {
1156
+ description: "Render and independently verify one immutable Framekit revision without launching an NLE.",
1157
+ inputSchema: {
1158
+ projectId: z.string().min(1),
1159
+ sequenceId: z.string().min(1),
1160
+ expectedRevision: revisionValueSchema.optional(),
1161
+ parameters: headlessRenderParametersSchema,
1162
+ },
1163
+ }, async ({ projectId, sequenceId, expectedRevision, parameters }) => sessionResult(() => requireHeadlessProjects().render(projectId, sequenceId, parameters, expectedRevision)));
1164
+ server.registerTool("headless.render.inspect", {
1165
+ description: "Inspect a persisted headless render record, provenance, and independent verification evidence.",
1166
+ inputSchema: { renderId: z.string().min(1) },
1167
+ }, async ({ renderId }) => sessionResult(() => requireHeadlessProjects().inspectRender(renderId)));
1040
1168
  server.registerTool("editor.inspect", {
1041
1169
  description: "Read editor identity and machine-readable capabilities before selecting an editing path.",
1042
1170
  }, async () => {
@@ -1060,7 +1188,7 @@ export function createMcpServer(runtime, options = {}) {
1060
1188
  availableCapabilities: nativeMediaIntentCapabilities(options.nativeEditor),
1061
1189
  })));
1062
1190
  server.registerTool("editing.route", {
1063
- description: "Resolve an editor-first path after capability checks; never bypass a connected editor, and require explicit external fallback selection.",
1191
+ description: "Resolve the default headless SSoT path or an explicitly requested headed path after capability checks; never fall back to native UI implicitly, and require explicit external-renderer fallback selection.",
1064
1192
  inputSchema: {
1065
1193
  operation: z.enum([
1066
1194
  "project.list",
@@ -1077,10 +1205,17 @@ export function createMcpServer(runtime, options = {}) {
1077
1205
  "timeline.export",
1078
1206
  ]),
1079
1207
  fallback: z.enum(["none", "external-renderer"]).optional().default("none"),
1208
+ path: z.enum(["headless", "headed"]).optional(),
1209
+ editType: z.enum(EDITING_ROUTE_EDIT_TYPES).optional(),
1080
1210
  },
1081
- }, async ({ operation, fallback }) => {
1211
+ }, async ({ operation, fallback, path, editType }) => {
1082
1212
  const context = await editingRouteContext(runtime, options);
1083
- return jsonResult(resolveEditingRoute({ operation, fallback }, context));
1213
+ return jsonResult(resolveEditingRoute({
1214
+ operation,
1215
+ fallback,
1216
+ ...(path ? { path } : {}),
1217
+ ...(editType ? { editType } : {}),
1218
+ }, context));
1084
1219
  });
1085
1220
  server.registerTool("editing.duration.plan", {
1086
1221
  description: "Plan requested duration against unique footage and return explicit quality-preserving alternatives without editing.",
@@ -1415,7 +1550,7 @@ export function createMcpServer(runtime, options = {}) {
1415
1550
  return nativeMutationResult(() => options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
1416
1551
  });
1417
1552
  server.registerTool("artifact.publish.preview", {
1418
- description: "Prepare a headed-only publish handoff for a verified FCPXML artifact without opening Final Cut.",
1553
+ description: "Prepare a verified FCPXML publish handoff without opening Final Cut; the configured native route may use non-activating document delivery or an explicit headed fallback.",
1419
1554
  inputSchema: {
1420
1555
  artifactPath: z.string().trim().min(1),
1421
1556
  transactionId: z.string().min(1),
@@ -1615,8 +1750,27 @@ export function createMcpServer(runtime, options = {}) {
1615
1750
  timestamp: new Date(sequence).toISOString(),
1616
1751
  }, waitMs ?? 0)));
1617
1752
  server.registerTool("timeline.inspect", {
1618
- description: "Read the current canonical timeline snapshot after canonical capability checks.",
1619
- }, async () => {
1753
+ description: "Read a bound session baseline or perform an explicit canonical timeline resync after canonical capability checks.",
1754
+ inputSchema: timelineReadbackSchema,
1755
+ }, async ({ sessionId, requestedCanonical, finalVerification }) => {
1756
+ if (sessionId) {
1757
+ const { stored, decision } = await prepareSessionReadback(sessionId, requestedCanonical, finalVerification);
1758
+ if (decision.route === "session" || decision.route === "fast-observation") {
1759
+ return jsonResult({
1760
+ sessionId,
1761
+ readback: decision,
1762
+ session: stored.document,
1763
+ timeline: stored.document.base,
1764
+ });
1765
+ }
1766
+ const resynced = await canonicalResyncSession(sessionId, stored.document.provider?.id);
1767
+ return jsonResult({
1768
+ sessionId,
1769
+ readback: decision,
1770
+ snapshot: resynced.snapshot.timeline,
1771
+ session: resynced.session,
1772
+ });
1773
+ }
1620
1774
  const inspected = await inspectMcpEditor(runtime, options);
1621
1775
  const capability = inspected.capabilities.families.canonicalDocument.read;
1622
1776
  if (!capability.available) {
@@ -1717,8 +1871,10 @@ export function createMcpServer(runtime, options = {}) {
1717
1871
  description: "Apply one supported edit after editing.route confirms the required capabilities; return read-after-write plus its diff.",
1718
1872
  inputSchema: editToolInputSchema,
1719
1873
  }, async (input) => {
1720
- await requireEditingRoute(runtime, options, "timeline.edit");
1721
- return jsonResult(await runtime.edit(editOperationSchema.parse(input), input.verification ?? {}));
1874
+ const { path, verification, ...operation } = input;
1875
+ const parsedOperation = editOperationSchema.parse(operation);
1876
+ await requireEditingRoute(runtime, options, "timeline.edit", path, parsedOperation.type);
1877
+ return jsonResult(await runtime.edit(parsedOperation, verification ?? {}));
1722
1878
  });
1723
1879
  server.registerTool("rough-cut.construction.plan", {
1724
1880
  description: "Build a deterministic ordered rough-cut construction plan without changing the active project.",
@@ -1741,9 +1897,10 @@ export function createMcpServer(runtime, options = {}) {
1741
1897
  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.",
1742
1898
  inputSchema: editorTimelineEditToolInputSchema,
1743
1899
  }, async (input) => {
1744
- await requireEditingRoute(runtime, options, "timeline.edit");
1745
- const { projectId, sequenceId, verification, ...operation } = input;
1746
- return jsonResult(await runtime.editTimeline({ projectId, sequenceId }, editOperationSchema.parse(operation), verification ?? {}));
1900
+ const { path, projectId, sequenceId, verification, ...operation } = input;
1901
+ const parsedOperation = editOperationSchema.parse(operation);
1902
+ await requireEditingRoute(runtime, options, "timeline.edit", path, parsedOperation.type);
1903
+ return jsonResult(await runtime.editTimeline({ projectId, sequenceId }, parsedOperation, verification ?? {}));
1747
1904
  });
1748
1905
  server.registerTool("music.add", {
1749
1906
  description: "Preview adding a searched or imported music bed with placement, gain, and fades; execute the returned token with music.add.execute.",
@@ -1763,10 +1920,12 @@ export function createMcpServer(runtime, options = {}) {
1763
1920
  baseRevision: revisionValueSchema,
1764
1921
  operations: workflowOperationsSchema,
1765
1922
  verification: verificationPolicySchema.optional(),
1923
+ path: editingPathSchema,
1766
1924
  },
1767
1925
  }, async (request) => {
1768
- await requireEditingRoute(runtime, options, "timeline.edit");
1769
- return jsonResult(await runtime.previewEdit(request));
1926
+ const { path, ...editRequest } = request;
1927
+ await requireEditingRoute(runtime, options, "timeline.edit", path);
1928
+ return jsonResult(await runtime.previewEdit(editRequest));
1770
1929
  });
1771
1930
  server.registerTool("timeline.mask.add.preview", {
1772
1931
  description: "Preview a bounded or supplied-alpha mask against an explicit project, sequence, revision, and occurrence without mutation.",
@@ -1799,9 +1958,10 @@ export function createMcpServer(runtime, options = {}) {
1799
1958
  baseRevision: revisionValueSchema,
1800
1959
  operations: workflowOperationsSchema,
1801
1960
  verification: verificationPolicySchema.optional(),
1961
+ path: editingPathSchema,
1802
1962
  },
1803
- }, async ({ projectId, sequenceId, baseRevision, operations, verification }) => {
1804
- await requireEditingRoute(runtime, options, "timeline.edit");
1963
+ }, async ({ projectId, sequenceId, baseRevision, operations, verification, path }) => {
1964
+ await requireEditingRoute(runtime, options, "timeline.edit", path);
1805
1965
  return jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, { baseRevision, operations, ...(verification ? { verification } : {}) }));
1806
1966
  });
1807
1967
  server.registerTool("artifact.edit.execute", {
@@ -1840,16 +2000,16 @@ export function createMcpServer(runtime, options = {}) {
1840
2000
  });
1841
2001
  server.registerTool("editor.timeline.edit.execute", {
1842
2002
  description: "Execute one short-lived live timeline edit preview token exactly once and verify the timeline transaction.",
1843
- inputSchema: { previewToken: z.string().min(1) },
1844
- }, async ({ previewToken }) => {
1845
- await requireEditingRoute(runtime, options, "timeline.edit");
2003
+ inputSchema: { previewToken: z.string().min(1), path: editingPathSchema },
2004
+ }, async ({ previewToken, path }) => {
2005
+ await requireEditingRoute(runtime, options, "timeline.edit", path);
1846
2006
  return jsonResult(await runtime.executeEdit(previewToken));
1847
2007
  });
1848
2008
  server.registerTool("timeline.edit.execute", {
1849
2009
  description: "Execute one short-lived composite edit preview token exactly once after editing.route capability checks, then verify the transaction.",
1850
- inputSchema: { previewToken: z.string().min(1) },
1851
- }, async ({ previewToken }) => {
1852
- await requireEditingRoute(runtime, options, "timeline.edit");
2010
+ inputSchema: { previewToken: z.string().min(1), path: editingPathSchema },
2011
+ }, async ({ previewToken, path }) => {
2012
+ await requireEditingRoute(runtime, options, "timeline.edit", path);
1853
2013
  return jsonResult(await runtime.executeEdit(previewToken));
1854
2014
  });
1855
2015
  server.registerTool("timeline.mask.add.execute", {
@@ -2068,6 +2228,11 @@ async function inspectMcpEditor(runtime, options) {
2068
2228
  const inspected = await runtime.inspectEditor();
2069
2229
  const native = options.nativeEditor?.capabilities();
2070
2230
  const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
2231
+ const publishingMode = publishingAvailable
2232
+ ? (typeof options.projectPublisher?.executionMode === "function"
2233
+ ? options.projectPublisher.executionMode()
2234
+ : "headed-only")
2235
+ : "unavailable";
2071
2236
  const exportAvailable = Boolean(options.videoExporter?.isAvailable());
2072
2237
  const backgroundExportAvailable = Boolean(options.backgroundRenderer?.isAvailable());
2073
2238
  const capabilities = withCapabilityFamilies({
@@ -2075,7 +2240,7 @@ async function inspectMcpEditor(runtime, options) {
2075
2240
  editor: {
2076
2241
  ...inspected.capabilities.editor,
2077
2242
  artifactPublish: publishingAvailable,
2078
- artifactPublishMode: publishingAvailable ? "headed-only" : "unavailable",
2243
+ artifactPublishMode: publishingMode,
2079
2244
  ...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
2080
2245
  videoExport: exportAvailable,
2081
2246
  backgroundRender: backgroundExportAvailable,
@@ -2109,7 +2274,7 @@ async function inspectMcpEditor(runtime, options) {
2109
2274
  clipMovement: false,
2110
2275
  },
2111
2276
  publishing: publishingAvailable,
2112
- publishingBackend: "fcpxml-publisher",
2277
+ publishingBackend: publishingMode === "background-capable" ? "fcpxml-document-open" : "fcpxml-publisher",
2113
2278
  export: exportAvailable,
2114
2279
  exportBackend: "final-cut-native-export",
2115
2280
  backgroundExport: {
@@ -2156,8 +2321,15 @@ function requireArtifactTransaction(runtime, transactionId, artifactPath) {
2156
2321
  }
2157
2322
  return transaction;
2158
2323
  }
2159
- async function requireEditingRoute(runtime, options, operation) {
2160
- const route = resolveEditingRoute({ operation }, await editingRouteContext(runtime, options));
2324
+ async function requireEditingRoute(runtime, options, operation, path, editType) {
2325
+ const route = resolveEditingRoute({
2326
+ operation,
2327
+ ...(path ? { path } : {}),
2328
+ ...(editType ? { editType } : {}),
2329
+ }, await editingRouteContext(runtime, options));
2330
+ if (route.status === "headless-selected") {
2331
+ throw new Error("HEADLESS_ROUTE_SELECTED: use the headless.project and headless.edit tools for the default Framekit SSoT path");
2332
+ }
2161
2333
  if (route.status !== "editor-selected") {
2162
2334
  throw new Error(`${route.reason.code}: ${route.reason.message}`);
2163
2335
  }
@@ -2183,6 +2355,17 @@ async function editingRouteContext(runtime, options) {
2183
2355
  return {
2184
2356
  connection,
2185
2357
  ...(editor ? { editor } : {}),
2358
+ ...(options.headlessProjects ? {
2359
+ headless: {
2360
+ available: true,
2361
+ backend: "framekit-project-store",
2362
+ guarantee: "canonical-write",
2363
+ // Advertise only concrete Timeline IR edit capabilities. The legacy
2364
+ // timeline.edit surface also accepts operations that the headless
2365
+ // transaction layer does not implement.
2366
+ supportedOperations: HEADLESS_TIMELINE_EDIT_TYPES.map((editType) => `timeline.edit:${editType}`),
2367
+ },
2368
+ } : {}),
2186
2369
  ...(options.nativeEditor ? { native: { ...options.nativeEditor.capabilities() } } : {}),
2187
2370
  ...(nativeReadiness ? { nativeReadiness } : {}),
2188
2371
  };