@morshoto/framekit 0.1.14 → 0.1.17

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 (36) 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/connection.js +8 -5
  4. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +36 -7
  5. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +21 -7
  6. package/dist-package/adapters/final-cut/typescript/src/index.js +2 -0
  7. package/dist-package/adapters/final-cut/typescript/src/live.js +56 -1
  8. package/dist-package/adapters/final-cut/typescript/src/native.js +311 -20
  9. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.js +312 -0
  10. package/dist-package/adapters/final-cut/typescript/src/publisher.js +68 -8
  11. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.js +263 -0
  12. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +179 -25
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +62 -0
  14. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +551 -0
  15. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +181 -0
  16. package/dist-package/adapters/headless/typescript/src/index.js +3 -0
  17. package/dist-package/apps/mcp-server/src/headless-projects.js +370 -0
  18. package/dist-package/apps/mcp-server/src/headless-sessions.js +3 -0
  19. package/dist-package/apps/mcp-server/src/main.js +28 -4
  20. package/dist-package/apps/mcp-server/src/materialization-jobs.js +233 -4
  21. package/dist-package/apps/mcp-server/src/readback-policy.js +26 -0
  22. package/dist-package/apps/mcp-server/src/routing.js +134 -5
  23. package/dist-package/apps/mcp-server/src/server.js +311 -34
  24. package/dist-package/packages/runtime/src/application/local-media.js +157 -0
  25. package/dist-package/packages/runtime/src/application/media-analysis-service.js +347 -27
  26. package/dist-package/packages/runtime/src/application/project-store.js +234 -0
  27. package/dist-package/packages/runtime/src/application/project-transactions.js +227 -0
  28. package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
  29. package/dist-package/packages/runtime/src/index.js +7 -0
  30. package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
  31. package/dist-package/packages/runtime/src/render/render-and-verify.js +126 -0
  32. package/dist-package/packages/runtime/src/render/render-contract.js +146 -0
  33. package/dist-package/packages/runtime/src/runtime.js +5 -2
  34. package/dist-package/packages/runtime/src/timeline/editing-session.js +277 -9
  35. package/dist-package/packages/runtime/src/timeline/fast-observation.js +141 -0
  36. package/package.json +2 -1
@@ -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(),
@@ -44,6 +50,10 @@ const mediaIndexQuerySchema = z.object({
44
50
  range: rangeSchema.optional(),
45
51
  capabilities: z.array(z.enum(["metadata", "speech", "audio", "noise", "visual"])).optional(),
46
52
  });
53
+ const timelineSemanticContextQuerySchema = z.object({
54
+ query: z.string().optional(),
55
+ occurrenceIds: z.array(z.string().min(1)).optional(),
56
+ }).strict();
47
57
  const roughCutPlanSchema = mediaIndexQuerySchema.extend({
48
58
  maxShots: z.number().int().positive().optional(),
49
59
  });
@@ -165,6 +175,7 @@ const editOperationSchema = z.discriminatedUnion("type", [
165
175
  rippleDeleteSchema,
166
176
  addMarkerSchema,
167
177
  ]);
178
+ const editingPathSchema = z.enum(["headless", "headed"]).optional();
168
179
  const verificationAssertionSchema = z.discriminatedUnion("type", [
169
180
  z.object({
170
181
  type: z.literal("audio-audibility"),
@@ -268,13 +279,14 @@ function createEditToolInputSchema(target = {}, baseRevision = revisionSchema) {
268
279
  ];
269
280
  return mcpDiscriminatedUnion(options);
270
281
  }
271
- const editToolInputSchema = createEditToolInputSchema();
282
+ const editToolInputSchema = createEditToolInputSchema({ path: editingPathSchema });
272
283
  const artifactEditToolInputSchema = createEditToolInputSchema({
273
284
  artifactPath: z.string().trim().min(1),
274
285
  }, revisionValueSchema);
275
286
  const editorTimelineEditToolInputSchema = createEditToolInputSchema({
276
287
  projectId: z.string().trim().min(1),
277
288
  sequenceId: z.string().trim().min(1),
289
+ path: editingPathSchema,
278
290
  }, revisionValueSchema);
279
291
  function exposeObjectRoot(schema) {
280
292
  if (!isRecord(schema) || !Array.isArray(schema.anyOf))
@@ -824,7 +836,7 @@ function frameResult(value) {
824
836
  }
825
837
  export function createMcpServer(runtime, options = {}) {
826
838
  runtime.registerBuiltinSkills();
827
- const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: EDITOR_FIRST_MCP_INSTRUCTIONS });
839
+ const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: options.headlessProjects ? HEADLESS_FIRST_MCP_INSTRUCTIONS : EDITOR_FIRST_MCP_INSTRUCTIONS });
828
840
  const nativeTransitionAssets = new Map();
829
841
  const sessions = options.sessionDirectory
830
842
  ? new EditingSessionRepository(options.sessionDirectory, options.sessionChangeSource)
@@ -842,6 +854,37 @@ export function createMcpServer(runtime, options = {}) {
842
854
  throw new Error("MATERIALIZATION_STORAGE_UNAVAILABLE: configure a materialization directory");
843
855
  return materializations;
844
856
  };
857
+ const requireHeadlessProjects = () => {
858
+ if (!options.headlessProjects)
859
+ throw new Error("HEADLESS_PROJECT_UNAVAILABLE: headless project storage is not configured");
860
+ return options.headlessProjects;
861
+ };
862
+ const prepareSessionReadback = async (sessionId, requestedCanonical, finalVerification) => {
863
+ const stored = await requireSessions().inspect(sessionId);
864
+ const decision = chooseTimelineReadback({
865
+ hasCanonicalBase: true,
866
+ requestedCanonical,
867
+ finalVerification,
868
+ sessionState: stored.document.state,
869
+ ...(stored.document.observation ? {
870
+ fastObservation: {
871
+ available: true,
872
+ coverageComplete: stored.document.observation.coverageComplete,
873
+ status: "possibly-stale",
874
+ },
875
+ } : {}),
876
+ });
877
+ return { stored, decision };
878
+ };
879
+ const canonicalResyncSession = async (sessionId, providerId) => {
880
+ if (providerId && providerId !== "final-cut") {
881
+ throw new Error(`SESSION_PROVIDER_MISMATCH: canonical Final Cut resync cannot replace provider ${providerId}`);
882
+ }
883
+ const snapshot = await runtime.inspectProject();
884
+ const timeline = createTimelineIrFromProjectSnapshot(snapshot, { id: "final-cut" });
885
+ const session = await requireSessions().reconcile(sessionId, { id: "final-cut" }, timeline);
886
+ return { snapshot, session };
887
+ };
845
888
  const sessionOperationSchema = z.array(z.unknown());
846
889
  server.registerTool("session.create", {
847
890
  description: "Create and atomically persist a provider-neutral editing session without mutating Final Cut.",
@@ -921,6 +964,10 @@ export function createMcpServer(runtime, options = {}) {
921
964
  description: "Resume a retryable persisted materialization job with its verified immutable artifact.",
922
965
  inputSchema: { jobId: z.string().min(1) },
923
966
  }, async ({ jobId }) => sessionResult(async () => requireMaterializations().retry(jobId)));
967
+ server.registerTool("session.materialize.resync", {
968
+ description: "Read the completed versioned handoff target and create a fresh editing-session baseline for continuation.",
969
+ inputSchema: { jobId: z.string().min(1), sessionId: z.string().min(1) },
970
+ }, async ({ jobId, sessionId }) => sessionResult(async () => requireMaterializations().resync(jobId, sessionId)));
924
971
  server.registerTool("connection.status", {
925
972
  description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
926
973
  inputSchema: {},
@@ -987,8 +1034,22 @@ export function createMcpServer(runtime, options = {}) {
987
1034
  }
988
1035
  });
989
1036
  server.registerTool("project.inspect", {
990
- description: "Read the current canonical project snapshot before editing.route selects a capability-checked path.",
991
- }, async () => {
1037
+ description: "Read a bound session baseline or perform an explicit canonical project resync before editing.route selects a capability-checked path.",
1038
+ inputSchema: timelineReadbackSchema,
1039
+ }, async ({ sessionId, requestedCanonical, finalVerification }) => {
1040
+ if (sessionId) {
1041
+ const { stored, decision } = await prepareSessionReadback(sessionId, requestedCanonical, finalVerification);
1042
+ if (decision.route === "session" || decision.route === "fast-observation") {
1043
+ return jsonResult({
1044
+ sessionId,
1045
+ readback: decision,
1046
+ session: stored.document,
1047
+ snapshot: stored.document.base,
1048
+ });
1049
+ }
1050
+ const resynced = await canonicalResyncSession(sessionId, stored.document.provider?.id);
1051
+ return jsonResult({ sessionId, readback: decision, ...resynced });
1052
+ }
992
1053
  const inspected = await inspectMcpEditor(runtime, options);
993
1054
  const capability = inspected.capabilities.families.canonicalDocument.read;
994
1055
  if (!capability.available) {
@@ -1037,6 +1098,151 @@ export function createMcpServer(runtime, options = {}) {
1037
1098
  return capabilityUnavailableErrorResult(error);
1038
1099
  }
1039
1100
  });
1101
+ server.registerTool("headless.project.create", {
1102
+ description: "Create and persist a Framekit-owned canonical project without contacting Final Cut Pro.",
1103
+ inputSchema: { timeline: z.unknown() },
1104
+ }, async ({ timeline }) => sessionResult(async () => requireHeadlessProjects().create(timeline)));
1105
+ server.registerTool("headless.project.list", {
1106
+ description: "List persisted Framekit-owned projects and their stable canonical revisions.",
1107
+ inputSchema: {},
1108
+ }, async () => sessionResult(() => requireHeadlessProjects().list()));
1109
+ server.registerTool("headless.project.open", {
1110
+ description: "Open a persisted Framekit-owned project and fail closed if registered media changed or is missing.",
1111
+ inputSchema: { projectId: z.string().min(1) },
1112
+ }, async ({ projectId }) => sessionResult(() => requireHeadlessProjects().open(projectId)));
1113
+ server.registerTool("headless.project.inspect", {
1114
+ description: "Inspect the current persisted Framekit Timeline IR and exact revision.",
1115
+ inputSchema: { projectId: z.string().min(1) },
1116
+ }, async ({ projectId }) => sessionResult(() => requireHeadlessProjects().inspect(projectId)));
1117
+ server.registerTool("headless.media.register", {
1118
+ description: "Register one local source file in the canonical Framekit project with digest and ffprobe metadata.",
1119
+ inputSchema: {
1120
+ projectId: z.string().min(1),
1121
+ sourcePath: z.string().min(1),
1122
+ expectedRevision: revisionValueSchema.optional(),
1123
+ },
1124
+ }, async ({ projectId, sourcePath, expectedRevision }) => sessionResult(() => requireHeadlessProjects().registerMedia(projectId, sourcePath, expectedRevision)));
1125
+ server.registerTool("headless.edit.preview", {
1126
+ description: "Preview supported Framekit Timeline IR edits without persisting or mutating the project.",
1127
+ inputSchema: {
1128
+ projectId: z.string().min(1),
1129
+ sequenceId: z.string().min(1),
1130
+ expectedRevision: revisionValueSchema,
1131
+ operations: z.array(z.unknown()),
1132
+ },
1133
+ }, async ({ projectId, sequenceId, expectedRevision, operations }) => sessionResult(() => requireHeadlessProjects().previewEdit(projectId, {
1134
+ schemaVersion: 1,
1135
+ expectedRevision,
1136
+ operations: operations,
1137
+ }, sequenceId)));
1138
+ server.registerTool("headless.edit.execute", {
1139
+ description: "Execute supported Framekit Timeline IR edits against the expected canonical revision and persist exactly one revision.",
1140
+ inputSchema: {
1141
+ projectId: z.string().min(1),
1142
+ sequenceId: z.string().min(1),
1143
+ expectedRevision: revisionValueSchema,
1144
+ operations: z.array(z.unknown()),
1145
+ },
1146
+ }, async ({ projectId, sequenceId, expectedRevision, operations }) => sessionResult(() => requireHeadlessProjects().executeEdit(projectId, {
1147
+ schemaVersion: 1,
1148
+ expectedRevision,
1149
+ operations: operations,
1150
+ }, sequenceId)));
1151
+ const headlessRenderParametersSchema = z.object({
1152
+ outputPath: z.string().min(1),
1153
+ format: z.enum(["mp4", "mov"]),
1154
+ width: z.number().int().positive(),
1155
+ height: z.number().int().positive(),
1156
+ frameRate: rationalTimeSchema,
1157
+ overwrite: z.boolean().optional(),
1158
+ }).strict();
1159
+ const roughCutExecutionPlanSchema = z.object({
1160
+ planner: z.object({ id: z.string().min(1), version: z.number().int().nonnegative() }).strict(),
1161
+ revision: revisionValueSchema,
1162
+ query: z.record(z.unknown()),
1163
+ shots: z.array(z.object({
1164
+ order: z.number().int().positive(),
1165
+ sourceIdentity: z.object({
1166
+ mediaId: z.string().min(1),
1167
+ source: z.string().min(1),
1168
+ sourceDigest: z.string().optional(),
1169
+ mediaKind: z.enum(["video", "audio"]).optional(),
1170
+ duration: z.number().finite().positive().optional(),
1171
+ }).strict(),
1172
+ range: z.object({
1173
+ start: z.number().finite().nonnegative(),
1174
+ end: z.number().finite().positive(),
1175
+ startTime: rationalTimeSchema.optional(),
1176
+ durationTime: rationalTimeSchema.optional(),
1177
+ }).strict(),
1178
+ confidence: z.number().finite().nonnegative(),
1179
+ matchedProperties: z.array(z.string()),
1180
+ rationale: z.string().min(1),
1181
+ evidence: z.object({
1182
+ kind: z.literal("speech"),
1183
+ transcript: z.string(),
1184
+ wordCount: z.number().int().nonnegative(),
1185
+ averageWordConfidence: z.number().finite().min(0).max(1),
1186
+ vad: z.object({
1187
+ kind: z.enum(["speech", "silence", "breath", "laughter", "noise"]),
1188
+ confidence: z.number().finite().min(0).max(1).optional(),
1189
+ }).strict().optional(),
1190
+ audio: z.object({
1191
+ integratedLufs: z.number().finite().optional(),
1192
+ truePeakDb: z.number().finite().optional(),
1193
+ silenceMs: z.number().finite().nonnegative().optional(),
1194
+ }).strict().optional(),
1195
+ }).strict().optional(),
1196
+ }).strict()),
1197
+ warnings: z.array(z.string()),
1198
+ }).strict();
1199
+ const headlessFcpxmlTargetSchema = z.object({
1200
+ provider: z.literal("final-cut"),
1201
+ libraryUid: z.string().min(1),
1202
+ eventUid: z.string().min(1),
1203
+ projectUid: z.string().min(1),
1204
+ sequenceUid: z.string().min(1),
1205
+ eventName: z.string().min(1).optional(),
1206
+ materialization: z.enum(["versioned", "reuse-existing"]).optional(),
1207
+ }).strict();
1208
+ const headlessRoughCutRequestSchema = z.object({
1209
+ projectId: z.string().min(1),
1210
+ sequenceId: z.string().min(1),
1211
+ plan: roughCutExecutionPlanSchema,
1212
+ operations: z.array(z.unknown()).optional().describe("Ordered Timeline IR edit operations included in the preview and bound into planDigest."),
1213
+ sourceAudioPolicy: z.literal("preserve-and-mix").optional().describe("Retain source audio and mix registered audio/music occurrences using their configured gain."),
1214
+ render: headlessRenderParametersSchema,
1215
+ fcpxml: z.object({
1216
+ path: z.string().min(1),
1217
+ target: headlessFcpxmlTargetSchema,
1218
+ overwrite: z.boolean().optional(),
1219
+ }).strict(),
1220
+ }).strict();
1221
+ server.registerTool("headless.render", {
1222
+ description: "Render and independently verify one immutable Framekit revision without launching an NLE.",
1223
+ inputSchema: {
1224
+ projectId: z.string().min(1),
1225
+ sequenceId: z.string().min(1),
1226
+ expectedRevision: revisionValueSchema.optional(),
1227
+ parameters: headlessRenderParametersSchema,
1228
+ },
1229
+ }, async ({ projectId, sequenceId, expectedRevision, parameters }) => sessionResult(() => requireHeadlessProjects().render(projectId, sequenceId, parameters, expectedRevision)));
1230
+ server.registerTool("headless.rough-cut.preview", {
1231
+ description: "Preview a semantic rough-cut plan with optional Timeline IR operations; the digest binds both, and preview returns provenance and FCPXML output intent without mutation.",
1232
+ inputSchema: headlessRoughCutRequestSchema.shape,
1233
+ }, async (request) => sessionResult(() => requireHeadlessProjects().previewRoughCut(request)));
1234
+ server.registerTool("headless.rough-cut.execute", {
1235
+ description: "Execute an explicitly approved semantic rough-cut plan and its digest-bound Timeline IR operations headlessly, verify MP4 output, and write equivalent editable FCPXML.",
1236
+ inputSchema: {
1237
+ ...headlessRoughCutRequestSchema.shape,
1238
+ approved: z.boolean(),
1239
+ planDigest: z.string().regex(/^[a-f0-9]{64}$/),
1240
+ },
1241
+ }, async (request) => sessionResult(() => requireHeadlessProjects().executeRoughCut(request)));
1242
+ server.registerTool("headless.render.inspect", {
1243
+ description: "Inspect a persisted headless render record, provenance, and independent verification evidence.",
1244
+ inputSchema: { renderId: z.string().min(1) },
1245
+ }, async ({ renderId }) => sessionResult(() => requireHeadlessProjects().inspectRender(renderId)));
1040
1246
  server.registerTool("editor.inspect", {
1041
1247
  description: "Read editor identity and machine-readable capabilities before selecting an editing path.",
1042
1248
  }, async () => {
@@ -1060,7 +1266,7 @@ export function createMcpServer(runtime, options = {}) {
1060
1266
  availableCapabilities: nativeMediaIntentCapabilities(options.nativeEditor),
1061
1267
  })));
1062
1268
  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.",
1269
+ 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
1270
  inputSchema: {
1065
1271
  operation: z.enum([
1066
1272
  "project.list",
@@ -1077,10 +1283,17 @@ export function createMcpServer(runtime, options = {}) {
1077
1283
  "timeline.export",
1078
1284
  ]),
1079
1285
  fallback: z.enum(["none", "external-renderer"]).optional().default("none"),
1286
+ path: z.enum(["headless", "headed"]).optional(),
1287
+ editType: z.enum(EDITING_ROUTE_EDIT_TYPES).optional(),
1080
1288
  },
1081
- }, async ({ operation, fallback }) => {
1289
+ }, async ({ operation, fallback, path, editType }) => {
1082
1290
  const context = await editingRouteContext(runtime, options);
1083
- return jsonResult(resolveEditingRoute({ operation, fallback }, context));
1291
+ return jsonResult(resolveEditingRoute({
1292
+ operation,
1293
+ fallback,
1294
+ ...(path ? { path } : {}),
1295
+ ...(editType ? { editType } : {}),
1296
+ }, context));
1084
1297
  });
1085
1298
  server.registerTool("editing.duration.plan", {
1086
1299
  description: "Plan requested duration against unique footage and return explicit quality-preserving alternatives without editing.",
@@ -1415,7 +1628,7 @@ export function createMcpServer(runtime, options = {}) {
1415
1628
  return nativeMutationResult(() => options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
1416
1629
  });
1417
1630
  server.registerTool("artifact.publish.preview", {
1418
- description: "Prepare a headed-only publish handoff for a verified FCPXML artifact without opening Final Cut.",
1631
+ 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
1632
  inputSchema: {
1420
1633
  artifactPath: z.string().trim().min(1),
1421
1634
  transactionId: z.string().min(1),
@@ -1615,8 +1828,27 @@ export function createMcpServer(runtime, options = {}) {
1615
1828
  timestamp: new Date(sequence).toISOString(),
1616
1829
  }, waitMs ?? 0)));
1617
1830
  server.registerTool("timeline.inspect", {
1618
- description: "Read the current canonical timeline snapshot after canonical capability checks.",
1619
- }, async () => {
1831
+ description: "Read a bound session baseline or perform an explicit canonical timeline resync after canonical capability checks.",
1832
+ inputSchema: timelineReadbackSchema,
1833
+ }, async ({ sessionId, requestedCanonical, finalVerification }) => {
1834
+ if (sessionId) {
1835
+ const { stored, decision } = await prepareSessionReadback(sessionId, requestedCanonical, finalVerification);
1836
+ if (decision.route === "session" || decision.route === "fast-observation") {
1837
+ return jsonResult({
1838
+ sessionId,
1839
+ readback: decision,
1840
+ session: stored.document,
1841
+ timeline: stored.document.base,
1842
+ });
1843
+ }
1844
+ const resynced = await canonicalResyncSession(sessionId, stored.document.provider?.id);
1845
+ return jsonResult({
1846
+ sessionId,
1847
+ readback: decision,
1848
+ snapshot: resynced.snapshot.timeline,
1849
+ session: resynced.session,
1850
+ });
1851
+ }
1620
1852
  const inspected = await inspectMcpEditor(runtime, options);
1621
1853
  const capability = inspected.capabilities.families.canonicalDocument.read;
1622
1854
  if (!capability.available) {
@@ -1629,6 +1861,22 @@ export function createMcpServer(runtime, options = {}) {
1629
1861
  return capabilityUnavailableErrorResult(error);
1630
1862
  }
1631
1863
  });
1864
+ server.registerTool("timeline.semantic.inspect", {
1865
+ description: "Enrich timeline occurrences with source-range-bound semantic speech, visual, and metadata context without mutating the timeline.",
1866
+ inputSchema: timelineSemanticContextQuerySchema.shape,
1867
+ }, async (query) => {
1868
+ const inspected = await inspectMcpEditor(runtime, options);
1869
+ const capability = inspected.capabilities.families.canonicalDocument.read;
1870
+ if (!capability.available) {
1871
+ return capabilityErrorResult("timeline.semantic.inspect", "canonicalDocument.read", capability);
1872
+ }
1873
+ try {
1874
+ return jsonResult(await runtime.inspectTimelineSemanticContext(query));
1875
+ }
1876
+ catch (error) {
1877
+ return capabilityUnavailableErrorResult(error);
1878
+ }
1879
+ });
1632
1880
  server.registerTool("timeline.frame.capture", {
1633
1881
  description: "Capture an image at an exact timeline position with project, sequence, clip, and optional visual-analysis metadata.",
1634
1882
  inputSchema: {
@@ -1717,8 +1965,10 @@ export function createMcpServer(runtime, options = {}) {
1717
1965
  description: "Apply one supported edit after editing.route confirms the required capabilities; return read-after-write plus its diff.",
1718
1966
  inputSchema: editToolInputSchema,
1719
1967
  }, async (input) => {
1720
- await requireEditingRoute(runtime, options, "timeline.edit");
1721
- return jsonResult(await runtime.edit(editOperationSchema.parse(input), input.verification ?? {}));
1968
+ const { path, verification, ...operation } = input;
1969
+ const parsedOperation = editOperationSchema.parse(operation);
1970
+ await requireEditingRoute(runtime, options, "timeline.edit", path, parsedOperation.type);
1971
+ return jsonResult(await runtime.edit(parsedOperation, verification ?? {}));
1722
1972
  });
1723
1973
  server.registerTool("rough-cut.construction.plan", {
1724
1974
  description: "Build a deterministic ordered rough-cut construction plan without changing the active project.",
@@ -1741,9 +1991,10 @@ export function createMcpServer(runtime, options = {}) {
1741
1991
  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
1992
  inputSchema: editorTimelineEditToolInputSchema,
1743
1993
  }, 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 ?? {}));
1994
+ const { path, projectId, sequenceId, verification, ...operation } = input;
1995
+ const parsedOperation = editOperationSchema.parse(operation);
1996
+ await requireEditingRoute(runtime, options, "timeline.edit", path, parsedOperation.type);
1997
+ return jsonResult(await runtime.editTimeline({ projectId, sequenceId }, parsedOperation, verification ?? {}));
1747
1998
  });
1748
1999
  server.registerTool("music.add", {
1749
2000
  description: "Preview adding a searched or imported music bed with placement, gain, and fades; execute the returned token with music.add.execute.",
@@ -1763,10 +2014,12 @@ export function createMcpServer(runtime, options = {}) {
1763
2014
  baseRevision: revisionValueSchema,
1764
2015
  operations: workflowOperationsSchema,
1765
2016
  verification: verificationPolicySchema.optional(),
2017
+ path: editingPathSchema,
1766
2018
  },
1767
2019
  }, async (request) => {
1768
- await requireEditingRoute(runtime, options, "timeline.edit");
1769
- return jsonResult(await runtime.previewEdit(request));
2020
+ const { path, ...editRequest } = request;
2021
+ await requireEditingRoute(runtime, options, "timeline.edit", path);
2022
+ return jsonResult(await runtime.previewEdit(editRequest));
1770
2023
  });
1771
2024
  server.registerTool("timeline.mask.add.preview", {
1772
2025
  description: "Preview a bounded or supplied-alpha mask against an explicit project, sequence, revision, and occurrence without mutation.",
@@ -1799,9 +2052,10 @@ export function createMcpServer(runtime, options = {}) {
1799
2052
  baseRevision: revisionValueSchema,
1800
2053
  operations: workflowOperationsSchema,
1801
2054
  verification: verificationPolicySchema.optional(),
2055
+ path: editingPathSchema,
1802
2056
  },
1803
- }, async ({ projectId, sequenceId, baseRevision, operations, verification }) => {
1804
- await requireEditingRoute(runtime, options, "timeline.edit");
2057
+ }, async ({ projectId, sequenceId, baseRevision, operations, verification, path }) => {
2058
+ await requireEditingRoute(runtime, options, "timeline.edit", path);
1805
2059
  return jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, { baseRevision, operations, ...(verification ? { verification } : {}) }));
1806
2060
  });
1807
2061
  server.registerTool("artifact.edit.execute", {
@@ -1840,16 +2094,16 @@ export function createMcpServer(runtime, options = {}) {
1840
2094
  });
1841
2095
  server.registerTool("editor.timeline.edit.execute", {
1842
2096
  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");
2097
+ inputSchema: { previewToken: z.string().min(1), path: editingPathSchema },
2098
+ }, async ({ previewToken, path }) => {
2099
+ await requireEditingRoute(runtime, options, "timeline.edit", path);
1846
2100
  return jsonResult(await runtime.executeEdit(previewToken));
1847
2101
  });
1848
2102
  server.registerTool("timeline.edit.execute", {
1849
2103
  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");
2104
+ inputSchema: { previewToken: z.string().min(1), path: editingPathSchema },
2105
+ }, async ({ previewToken, path }) => {
2106
+ await requireEditingRoute(runtime, options, "timeline.edit", path);
1853
2107
  return jsonResult(await runtime.executeEdit(previewToken));
1854
2108
  });
1855
2109
  server.registerTool("timeline.mask.add.execute", {
@@ -1872,9 +2126,9 @@ export function createMcpServer(runtime, options = {}) {
1872
2126
  inputSchema: { previewToken: z.string().min(1) },
1873
2127
  }, async ({ previewToken }) => jsonResult(await runtime.executeFillerRemoval(previewToken)));
1874
2128
  server.registerTool("audio.analyze", {
1875
- description: "Analyze loudness, true peak, and silence for one media item.",
1876
- inputSchema: { mediaId: z.string().min(1) },
1877
- }, async ({ mediaId }) => jsonResult(await runtime.analyzeAudio(mediaId)));
2129
+ description: "Analyze loudness, true peak, and silence for one media item or source range.",
2130
+ inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
2131
+ }, async ({ mediaId, range }) => jsonResult(await runtime.analyzeAudio(mediaId, range)));
1878
2132
  server.registerTool("audio.noise.analyze", {
1879
2133
  description: "Analyze unwanted background noise for one media item when a noise analyzer is configured.",
1880
2134
  inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
@@ -2068,6 +2322,11 @@ async function inspectMcpEditor(runtime, options) {
2068
2322
  const inspected = await runtime.inspectEditor();
2069
2323
  const native = options.nativeEditor?.capabilities();
2070
2324
  const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
2325
+ const publishingMode = publishingAvailable
2326
+ ? (typeof options.projectPublisher?.executionMode === "function"
2327
+ ? options.projectPublisher.executionMode()
2328
+ : "headed-only")
2329
+ : "unavailable";
2071
2330
  const exportAvailable = Boolean(options.videoExporter?.isAvailable());
2072
2331
  const backgroundExportAvailable = Boolean(options.backgroundRenderer?.isAvailable());
2073
2332
  const capabilities = withCapabilityFamilies({
@@ -2075,7 +2334,7 @@ async function inspectMcpEditor(runtime, options) {
2075
2334
  editor: {
2076
2335
  ...inspected.capabilities.editor,
2077
2336
  artifactPublish: publishingAvailable,
2078
- artifactPublishMode: publishingAvailable ? "headed-only" : "unavailable",
2337
+ artifactPublishMode: publishingMode,
2079
2338
  ...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
2080
2339
  videoExport: exportAvailable,
2081
2340
  backgroundRender: backgroundExportAvailable,
@@ -2109,7 +2368,7 @@ async function inspectMcpEditor(runtime, options) {
2109
2368
  clipMovement: false,
2110
2369
  },
2111
2370
  publishing: publishingAvailable,
2112
- publishingBackend: "fcpxml-publisher",
2371
+ publishingBackend: publishingMode === "background-capable" ? "fcpxml-document-open" : "fcpxml-publisher",
2113
2372
  export: exportAvailable,
2114
2373
  exportBackend: "final-cut-native-export",
2115
2374
  backgroundExport: {
@@ -2156,8 +2415,15 @@ function requireArtifactTransaction(runtime, transactionId, artifactPath) {
2156
2415
  }
2157
2416
  return transaction;
2158
2417
  }
2159
- async function requireEditingRoute(runtime, options, operation) {
2160
- const route = resolveEditingRoute({ operation }, await editingRouteContext(runtime, options));
2418
+ async function requireEditingRoute(runtime, options, operation, path, editType) {
2419
+ const route = resolveEditingRoute({
2420
+ operation,
2421
+ ...(path ? { path } : {}),
2422
+ ...(editType ? { editType } : {}),
2423
+ }, await editingRouteContext(runtime, options));
2424
+ if (route.status === "headless-selected") {
2425
+ throw new Error("HEADLESS_ROUTE_SELECTED: use the headless.project and headless.edit tools for the default Framekit SSoT path");
2426
+ }
2161
2427
  if (route.status !== "editor-selected") {
2162
2428
  throw new Error(`${route.reason.code}: ${route.reason.message}`);
2163
2429
  }
@@ -2183,6 +2449,17 @@ async function editingRouteContext(runtime, options) {
2183
2449
  return {
2184
2450
  connection,
2185
2451
  ...(editor ? { editor } : {}),
2452
+ ...(options.headlessProjects ? {
2453
+ headless: {
2454
+ available: true,
2455
+ backend: "framekit-project-store",
2456
+ guarantee: "canonical-write",
2457
+ // Advertise only concrete Timeline IR edit capabilities. The legacy
2458
+ // timeline.edit surface also accepts operations that the headless
2459
+ // transaction layer does not implement.
2460
+ supportedOperations: HEADLESS_TIMELINE_EDIT_TYPES.map((editType) => `timeline.edit:${editType}`),
2461
+ },
2462
+ } : {}),
2186
2463
  ...(options.nativeEditor ? { native: { ...options.nativeEditor.capabilities() } } : {}),
2187
2464
  ...(nativeReadiness ? { nativeReadiness } : {}),
2188
2465
  };