@morshoto/framekit 0.1.16 → 0.1.18

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/README.md +10 -4
  2. package/dist-package/adapters/final-cut/typescript/src/canonical.js +19 -7
  3. package/dist-package/adapters/final-cut/typescript/src/connection.js +13 -8
  4. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +147 -34
  5. package/dist-package/adapters/final-cut/typescript/src/index.js +1 -0
  6. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +60 -1
  7. package/dist-package/adapters/final-cut/typescript/src/live.js +2 -2
  8. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +213 -0
  9. package/dist-package/adapters/final-cut/typescript/src/publisher.js +762 -238
  10. package/dist-package/adapters/final-cut/typescript/src/session.js +6 -1
  11. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +293 -59
  12. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +137 -19
  13. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.js +2 -2
  14. package/dist-package/apps/cli/src/main.js +34 -19
  15. package/dist-package/apps/mcp-server/src/build-alignment.js +59 -0
  16. package/dist-package/apps/mcp-server/src/build-identity.js +30 -0
  17. package/dist-package/apps/mcp-server/src/build-identity.json +5 -0
  18. package/dist-package/apps/mcp-server/src/headless-project-snapshot.js +101 -0
  19. package/dist-package/apps/mcp-server/src/headless-projects.js +473 -3
  20. package/dist-package/apps/mcp-server/src/main.js +33 -6
  21. package/dist-package/apps/mcp-server/src/server.js +367 -52
  22. package/dist-package/apps/mcp-server/src/version.js +21 -2
  23. package/dist-package/packages/runtime/src/application/media-analysis-service.js +360 -30
  24. package/dist-package/packages/runtime/src/application/semantic-media-index-store.js +86 -0
  25. package/dist-package/packages/runtime/src/index.js +1 -0
  26. package/dist-package/packages/runtime/src/planning/rough-cut.js +103 -7
  27. package/dist-package/packages/runtime/src/render/render-contract.js +3 -0
  28. package/dist-package/packages/runtime/src/runtime.js +11 -2
  29. package/dist-package/packages/runtime/src/timeline/editing-session.js +7 -2
  30. package/package.json +9 -9
@@ -1,13 +1,15 @@
1
1
  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
- import { z } from "zod";
4
+ import { z } from "zod/v3";
5
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
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
+ import { assessBuildAlignment } from "./build-alignment.js";
8
9
  import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
9
10
  import { EditingSessionRepository } from "./headless-sessions.js";
10
11
  import { SessionMaterializationJobs, } from "./materialization-jobs.js";
12
+ import { projectSnapshotFromTimelineIr } from "./headless-project-snapshot.js";
11
13
  import { chooseTimelineReadback } from "./readback-policy.js";
12
14
  const revisionValueSchema = z.object({
13
15
  id: z.string(),
@@ -50,8 +52,13 @@ const mediaIndexQuerySchema = z.object({
50
52
  range: rangeSchema.optional(),
51
53
  capabilities: z.array(z.enum(["metadata", "speech", "audio", "noise", "visual"])).optional(),
52
54
  });
55
+ const timelineSemanticContextQuerySchema = z.object({
56
+ query: z.string().optional(),
57
+ occurrenceIds: z.array(z.string().min(1)).optional(),
58
+ }).strict();
53
59
  const roughCutPlanSchema = mediaIndexQuerySchema.extend({
54
60
  maxShots: z.number().int().positive().optional(),
61
+ projectId: z.string().min(1).optional(),
55
62
  });
56
63
  const durationRangeSchema = z.object({
57
64
  startSeconds: z.number().finite().nonnegative(),
@@ -315,6 +322,7 @@ function installMcpSchemaCompatibility(server) {
315
322
  }
316
323
  const artifactPublishInputSchema = z.object({
317
324
  artifactPath: z.string().trim().min(1),
325
+ targetLibraryPath: z.string().trim().min(1),
318
326
  transactionId: z.string().min(1),
319
327
  confirm: z.boolean(),
320
328
  }).strict();
@@ -832,6 +840,29 @@ function frameResult(value) {
832
840
  }
833
841
  export function createMcpServer(runtime, options = {}) {
834
842
  runtime.registerBuiltinSkills();
843
+ if (options.requireBuildAlignment) {
844
+ const assertAlignment = () => assertRequiredBuildAlignment(runtime, options);
845
+ options = {
846
+ ...options,
847
+ ...(options.nativeEditor
848
+ ? { nativeEditor: withBuildAlignmentGuard(options.nativeEditor, assertAlignment, ["capabilities"]) }
849
+ : {}),
850
+ ...(options.disposableNative
851
+ ? { disposableNative: withBuildAlignmentGuard(options.disposableNative, assertAlignment) }
852
+ : {}),
853
+ ...(options.nativeOperationSession
854
+ ? { nativeOperationSession: withBuildAlignmentGuard(options.nativeOperationSession, assertAlignment) }
855
+ : {}),
856
+ ...(options.projectPublisher
857
+ ? {
858
+ projectPublisher: withBuildAlignmentGuard(options.projectPublisher, assertAlignment, ["isAvailable", "inspectReadiness", "executionMode", "getPublishJob"]),
859
+ }
860
+ : {}),
861
+ ...(options.videoExporter
862
+ ? { videoExporter: withBuildAlignmentGuard(options.videoExporter, assertAlignment, ["isAvailable"]) }
863
+ : {}),
864
+ };
865
+ }
835
866
  const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: options.headlessProjects ? HEADLESS_FIRST_MCP_INSTRUCTIONS : EDITOR_FIRST_MCP_INSTRUCTIONS });
836
867
  const nativeTransitionAssets = new Map();
837
868
  const sessions = options.sessionDirectory
@@ -968,6 +999,10 @@ export function createMcpServer(runtime, options = {}) {
968
999
  description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
969
1000
  inputSchema: {},
970
1001
  }, async () => jsonResult(await effectiveConnectionStatus(runtime, options)));
1002
+ server.registerTool("editor.native.handoff.readiness", {
1003
+ description: "Read native Final Cut handoff readiness without launching, activating, importing, or mutating Final Cut.",
1004
+ inputSchema: { publishJobId: z.string().trim().min(1).optional() },
1005
+ }, async ({ publishJobId }) => jsonResult(await inspectNativeHandoffReadiness(runtime, options, publishJobId)));
971
1006
  server.registerTool("skill.list", {
972
1007
  description: "List registered versioned Framekit Skills with current capability availability.",
973
1008
  inputSchema: {},
@@ -1152,6 +1187,68 @@ export function createMcpServer(runtime, options = {}) {
1152
1187
  frameRate: rationalTimeSchema,
1153
1188
  overwrite: z.boolean().optional(),
1154
1189
  }).strict();
1190
+ const roughCutExecutionPlanSchema = z.object({
1191
+ planner: z.object({ id: z.string().min(1), version: z.number().int().nonnegative() }).strict(),
1192
+ revision: revisionValueSchema,
1193
+ query: z.record(z.unknown()),
1194
+ shots: z.array(z.object({
1195
+ order: z.number().int().positive(),
1196
+ sourceIdentity: z.object({
1197
+ mediaId: z.string().min(1),
1198
+ source: z.string().min(1),
1199
+ sourceDigest: z.string().optional(),
1200
+ mediaKind: z.enum(["video", "audio"]).optional(),
1201
+ duration: z.number().finite().positive().optional(),
1202
+ }).strict(),
1203
+ range: z.object({
1204
+ start: z.number().finite().nonnegative(),
1205
+ end: z.number().finite().positive(),
1206
+ startTime: rationalTimeSchema.optional(),
1207
+ durationTime: rationalTimeSchema.optional(),
1208
+ }).strict(),
1209
+ confidence: z.number().finite().nonnegative(),
1210
+ matchedProperties: z.array(z.string()),
1211
+ rationale: z.string().min(1),
1212
+ evidence: z.object({
1213
+ kind: z.literal("speech"),
1214
+ transcript: z.string(),
1215
+ wordCount: z.number().int().nonnegative(),
1216
+ averageWordConfidence: z.number().finite().min(0).max(1),
1217
+ vad: z.object({
1218
+ kind: z.enum(["speech", "silence", "breath", "laughter", "noise"]),
1219
+ confidence: z.number().finite().min(0).max(1).optional(),
1220
+ }).strict().optional(),
1221
+ audio: z.object({
1222
+ integratedLufs: z.number().finite().optional(),
1223
+ truePeakDb: z.number().finite().optional(),
1224
+ silenceMs: z.number().finite().nonnegative().optional(),
1225
+ }).strict().optional(),
1226
+ }).strict().optional(),
1227
+ }).strict()),
1228
+ warnings: z.array(z.string()),
1229
+ }).strict();
1230
+ const headlessFcpxmlTargetSchema = z.object({
1231
+ provider: z.literal("final-cut"),
1232
+ libraryUid: z.string().min(1),
1233
+ eventUid: z.string().min(1),
1234
+ projectUid: z.string().min(1),
1235
+ sequenceUid: z.string().min(1),
1236
+ eventName: z.string().min(1).optional(),
1237
+ materialization: z.enum(["versioned", "reuse-existing"]).optional(),
1238
+ }).strict();
1239
+ const headlessRoughCutRequestSchema = z.object({
1240
+ projectId: z.string().min(1),
1241
+ sequenceId: z.string().min(1),
1242
+ plan: roughCutExecutionPlanSchema,
1243
+ operations: z.array(z.unknown()).optional().describe("Ordered Timeline IR edit operations included in the preview and bound into planDigest."),
1244
+ sourceAudioPolicy: z.literal("preserve-and-mix").optional().describe("Retain source audio and mix registered audio/music occurrences using their configured gain."),
1245
+ render: headlessRenderParametersSchema,
1246
+ fcpxml: z.object({
1247
+ path: z.string().min(1),
1248
+ target: headlessFcpxmlTargetSchema,
1249
+ overwrite: z.boolean().optional(),
1250
+ }).strict(),
1251
+ }).strict();
1155
1252
  server.registerTool("headless.render", {
1156
1253
  description: "Render and independently verify one immutable Framekit revision without launching an NLE.",
1157
1254
  inputSchema: {
@@ -1161,6 +1258,18 @@ export function createMcpServer(runtime, options = {}) {
1161
1258
  parameters: headlessRenderParametersSchema,
1162
1259
  },
1163
1260
  }, async ({ projectId, sequenceId, expectedRevision, parameters }) => sessionResult(() => requireHeadlessProjects().render(projectId, sequenceId, parameters, expectedRevision)));
1261
+ server.registerTool("headless.rough-cut.preview", {
1262
+ 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.",
1263
+ inputSchema: headlessRoughCutRequestSchema.shape,
1264
+ }, async (request) => sessionResult(() => requireHeadlessProjects().previewRoughCut(request)));
1265
+ server.registerTool("headless.rough-cut.execute", {
1266
+ 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.",
1267
+ inputSchema: {
1268
+ ...headlessRoughCutRequestSchema.shape,
1269
+ approved: z.boolean(),
1270
+ planDigest: z.string().regex(/^[a-f0-9]{64}$/),
1271
+ },
1272
+ }, async (request) => sessionResult(() => requireHeadlessProjects().executeRoughCut(request)));
1164
1273
  server.registerTool("headless.render.inspect", {
1165
1274
  description: "Inspect a persisted headless render record, provenance, and independent verification evidence.",
1166
1275
  inputSchema: { renderId: z.string().min(1) },
@@ -1209,7 +1318,11 @@ export function createMcpServer(runtime, options = {}) {
1209
1318
  editType: z.enum(EDITING_ROUTE_EDIT_TYPES).optional(),
1210
1319
  },
1211
1320
  }, async ({ operation, fallback, path, editType }) => {
1212
- const context = await editingRouteContext(runtime, options);
1321
+ const headlessOnly = fallback === "none"
1322
+ && (path === "headless" || (Boolean(options.headlessProjects) && operation === "timeline.edit" && path !== "headed"));
1323
+ const context = headlessOnly
1324
+ ? { connection: { state: "disconnected" }, ...headlessRoutingContext(options) }
1325
+ : await editingRouteContext(runtime, options);
1213
1326
  return jsonResult(resolveEditingRoute({
1214
1327
  operation,
1215
1328
  fallback,
@@ -1309,7 +1422,7 @@ export function createMcpServer(runtime, options = {}) {
1309
1422
  }, async ({ jobId }) => {
1310
1423
  if (!options.nativeOperationSession)
1311
1424
  throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
1312
- return jsonResult(options.nativeOperationSession.status(jobId));
1425
+ return jsonResult(await options.nativeOperationSession.status(jobId));
1313
1426
  });
1314
1427
  server.registerTool("editor.native.operation.retry", {
1315
1428
  description: "Retry a waiting native Final Cut operation after the required headed session becomes ready.",
@@ -1550,32 +1663,51 @@ export function createMcpServer(runtime, options = {}) {
1550
1663
  return nativeMutationResult(() => options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
1551
1664
  });
1552
1665
  server.registerTool("artifact.publish.preview", {
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.",
1666
+ description: "Prepare an experimental, opt-in native handoff from a verified artifact without opening Final Cut.",
1554
1667
  inputSchema: {
1555
1668
  artifactPath: z.string().trim().min(1),
1556
- transactionId: z.string().min(1),
1669
+ targetLibraryPath: z.string().trim().min(1),
1670
+ transactionId: z.string().min(1).optional(),
1671
+ headlessExecutionId: z.string().min(1).optional(),
1557
1672
  },
1558
- }, async ({ artifactPath, transactionId }) => {
1673
+ }, async ({ artifactPath, targetLibraryPath, transactionId, headlessExecutionId }) => {
1559
1674
  if (!options.projectPublisher)
1560
1675
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1561
- const transaction = runtime.getTransaction(transactionId);
1562
- if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
1563
- throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
1676
+ if (Boolean(transactionId) === Boolean(headlessExecutionId)) {
1677
+ throw new Error("PUBLISH_SOURCE_REQUIRED: provide exactly one of transactionId or headlessExecutionId");
1564
1678
  }
1565
- if (!transaction.artifactDigest) {
1566
- throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
1679
+ let sourceTransactionId;
1680
+ let artifactDigest;
1681
+ let sourceProof;
1682
+ if (headlessExecutionId) {
1683
+ sourceProof = await requireHeadlessProjects().verifyPublishableRoughCut(headlessExecutionId, artifactPath);
1684
+ sourceTransactionId = sourceProof.sourceTransactionId;
1685
+ artifactDigest = sourceProof.artifactDigest;
1567
1686
  }
1568
- const verification = await runtime.verifyTransaction(transactionId);
1569
- if (!verification.passed)
1570
- throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
1571
- return jsonResult(await options.projectPublisher.preparePublish({
1572
- sourceTransactionId: transactionId,
1687
+ else {
1688
+ const transaction = runtime.getTransaction(transactionId);
1689
+ if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
1690
+ throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
1691
+ }
1692
+ if (!transaction.artifactDigest) {
1693
+ throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
1694
+ }
1695
+ const verification = await runtime.verifyTransaction(transactionId);
1696
+ if (!verification.passed)
1697
+ throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
1698
+ sourceTransactionId = transactionId;
1699
+ artifactDigest = transaction.artifactDigest;
1700
+ }
1701
+ const job = await options.projectPublisher.preparePublish({
1702
+ sourceTransactionId,
1573
1703
  artifactPath,
1574
- artifactDigest: transaction.artifactDigest,
1575
- }));
1704
+ artifactDigest,
1705
+ targetLibraryPath,
1706
+ });
1707
+ return jsonResult({ ...job, ...(sourceProof ? { sourceProof } : {}) });
1576
1708
  });
1577
1709
  server.registerTool("artifact.publish.execute", {
1578
- description: "Execute a prepared artifact publish job after explicit confirmation and return only a verified or resumable state.",
1710
+ description: "Execute an experimental native handoff after explicit confirmation; dispatch alone is not project-creation proof, and success requires target readback.",
1579
1711
  inputSchema: {
1580
1712
  jobId: z.string().trim().min(1),
1581
1713
  confirm: z.literal(true),
@@ -1583,6 +1715,9 @@ export function createMcpServer(runtime, options = {}) {
1583
1715
  }, async ({ jobId, confirm }) => {
1584
1716
  if (!options.projectPublisher)
1585
1717
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1718
+ if (options.projectPublisher.isAvailable() && requiresHeadedPublishingRoute(options.projectPublisher)) {
1719
+ await requireEditingRoute(runtime, options, "timeline.publish.new-project");
1720
+ }
1586
1721
  return jsonResult(await options.projectPublisher.executePublishJob(jobId, confirm));
1587
1722
  });
1588
1723
  server.registerTool("artifact.publish.status", {
@@ -1594,11 +1729,14 @@ export function createMcpServer(runtime, options = {}) {
1594
1729
  return jsonResult(options.projectPublisher.getPublishJob(jobId));
1595
1730
  });
1596
1731
  server.registerTool("artifact.publish", {
1597
- description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project; requires explicit confirmation.",
1732
+ description: "Experimental, opt-in native import of validated FCPXML. Dispatch alone does not prove project creation; success requires matching created-target readback and explicit confirmation.",
1598
1733
  inputSchema: artifactPublishInputSchema,
1599
- }, async ({ artifactPath, transactionId, confirm }) => {
1600
- if (!options.projectPublisher)
1601
- throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1734
+ }, async ({ artifactPath, targetLibraryPath, transactionId, confirm }) => {
1735
+ if (!options.projectPublisher?.isAvailable())
1736
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
1737
+ if (requiresHeadedPublishingRoute(options.projectPublisher)) {
1738
+ await requireEditingRoute(runtime, options, "timeline.publish.new-project");
1739
+ }
1602
1740
  const transaction = runtime.getTransaction(transactionId);
1603
1741
  if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
1604
1742
  throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
@@ -1613,15 +1751,23 @@ export function createMcpServer(runtime, options = {}) {
1613
1751
  sourceTransactionId: transactionId,
1614
1752
  artifactPath,
1615
1753
  artifactDigest: transaction.artifactDigest,
1754
+ targetLibraryPath,
1616
1755
  confirm,
1617
1756
  }));
1618
1757
  });
1619
1758
  server.registerTool("timeline.publish.new-project", {
1620
- description: "Legacy alias for publishing a verified artifact transaction as a new Final Cut project.",
1621
- inputSchema: { transactionId: z.string().min(1) },
1622
- }, async ({ transactionId }) => {
1759
+ description: "Experimental, opt-in native import of a verified artifact transaction; reports verified delivery only after matching created-target readback and explicit confirmation.",
1760
+ inputSchema: {
1761
+ transactionId: z.string().min(1),
1762
+ targetLibraryPath: z.string().trim().min(1),
1763
+ confirm: z.literal(true),
1764
+ },
1765
+ }, async ({ transactionId, targetLibraryPath, confirm }) => {
1623
1766
  if (!options.projectPublisher?.isAvailable())
1624
- throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1767
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH, native writes, live project verification, and a target-binding provider");
1768
+ if (requiresHeadedPublishingRoute(options.projectPublisher)) {
1769
+ await requireEditingRoute(runtime, options, "timeline.publish.new-project");
1770
+ }
1625
1771
  const transaction = runtime.getTransaction(transactionId);
1626
1772
  if (transaction.target?.kind !== "artifact") {
1627
1773
  throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for a managed artifact`);
@@ -1636,7 +1782,8 @@ export function createMcpServer(runtime, options = {}) {
1636
1782
  sourceTransactionId: transactionId,
1637
1783
  artifactPath: transaction.target.artifactPath,
1638
1784
  artifactDigest: transaction.artifactDigest,
1639
- confirm: true,
1785
+ targetLibraryPath,
1786
+ confirm,
1640
1787
  }));
1641
1788
  });
1642
1789
  server.registerTool("timeline.export", {
@@ -1783,6 +1930,22 @@ export function createMcpServer(runtime, options = {}) {
1783
1930
  return capabilityUnavailableErrorResult(error);
1784
1931
  }
1785
1932
  });
1933
+ server.registerTool("timeline.semantic.inspect", {
1934
+ description: "Enrich timeline occurrences with source-range-bound semantic speech, visual, and metadata context without mutating the timeline.",
1935
+ inputSchema: timelineSemanticContextQuerySchema.shape,
1936
+ }, async (query) => {
1937
+ const inspected = await inspectMcpEditor(runtime, options);
1938
+ const capability = inspected.capabilities.families.canonicalDocument.read;
1939
+ if (!capability.available) {
1940
+ return capabilityErrorResult("timeline.semantic.inspect", "canonicalDocument.read", capability);
1941
+ }
1942
+ try {
1943
+ return jsonResult(await runtime.inspectTimelineSemanticContext(query));
1944
+ }
1945
+ catch (error) {
1946
+ return capabilityUnavailableErrorResult(error);
1947
+ }
1948
+ });
1786
1949
  server.registerTool("timeline.frame.capture", {
1787
1950
  description: "Capture an image at an exact timeline position with project, sequence, clip, and optional visual-analysis metadata.",
1788
1951
  inputSchema: {
@@ -1822,13 +1985,28 @@ export function createMcpServer(runtime, options = {}) {
1822
1985
  },
1823
1986
  }, async ({ mediaId, range }) => jsonResult(await runtime.analyzeVisual(mediaId, range)));
1824
1987
  server.registerTool("media.understand", {
1825
- description: "Return combined speech, audio, and visual understanding for one media item.",
1826
- inputSchema: { mediaId: z.string().min(1) },
1827
- }, async ({ mediaId }) => jsonResult(await runtime.understandMedia(mediaId)));
1988
+ description: "Return combined speech, audio, and visual understanding for one media item in the selected editor project or a named headless project.",
1989
+ inputSchema: { mediaId: z.string().min(1), projectId: z.string().min(1).optional() },
1990
+ }, async ({ mediaId, projectId }) => {
1991
+ if (!projectId)
1992
+ return jsonResult(await runtime.understandMedia(mediaId));
1993
+ return sessionResult(async () => {
1994
+ const project = await requireHeadlessProjects().open(projectId);
1995
+ return runtime.understandMediaInProject(mediaId, projectSnapshotFromTimelineIr(project.timeline));
1996
+ });
1997
+ });
1828
1998
  server.registerTool("rough-cut.plan", {
1829
- description: "Create a deterministic, explainable, read-only shot plan from analyzed media; does not mutate the timeline.",
1999
+ description: "Create a deterministic, explainable, read-only shot plan from analyzed editor or named headless project media; does not mutate the timeline.",
1830
2000
  inputSchema: roughCutPlanSchema.shape,
1831
- }, async (request) => jsonResult(await runtime.planRoughCut(request)));
2001
+ }, async (request) => {
2002
+ const { projectId, ...planRequest } = request;
2003
+ if (!projectId)
2004
+ return jsonResult(await runtime.planRoughCut(planRequest));
2005
+ return sessionResult(async () => {
2006
+ const project = await requireHeadlessProjects().open(projectId);
2007
+ return runtime.planRoughCutInProject(planRequest, projectSnapshotFromTimelineIr(project.timeline));
2008
+ });
2009
+ });
1832
2010
  server.registerTool("editor.assets", {
1833
2011
  description: "Search installed transitions, effects, titles, generators, and templates; filesystem discovery is the default and native Browser discovery is explicit.",
1834
2012
  inputSchema: {
@@ -2032,9 +2210,9 @@ export function createMcpServer(runtime, options = {}) {
2032
2210
  inputSchema: { previewToken: z.string().min(1) },
2033
2211
  }, async ({ previewToken }) => jsonResult(await runtime.executeFillerRemoval(previewToken)));
2034
2212
  server.registerTool("audio.analyze", {
2035
- description: "Analyze loudness, true peak, and silence for one media item.",
2036
- inputSchema: { mediaId: z.string().min(1) },
2037
- }, async ({ mediaId }) => jsonResult(await runtime.analyzeAudio(mediaId)));
2213
+ description: "Analyze loudness, true peak, and silence for one media item or source range.",
2214
+ inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
2215
+ }, async ({ mediaId, range }) => jsonResult(await runtime.analyzeAudio(mediaId, range)));
2038
2216
  server.registerTool("audio.noise.analyze", {
2039
2217
  description: "Analyze unwanted background noise for one media item when a noise analyzer is configured.",
2040
2218
  inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
@@ -2215,7 +2393,7 @@ async function effectiveConnectionStatus(runtime, options) {
2215
2393
  ...status,
2216
2394
  state: "unavailable",
2217
2395
  lastError: {
2218
- code: "CAPABILITY_UNAVAILABLE",
2396
+ code: message.match(/\bFRAMEKIT_[A-Z_]+\b/)?.[0] ?? "CAPABILITY_UNAVAILABLE",
2219
2397
  message: `effective runtime capability inspection failed: ${message}`,
2220
2398
  },
2221
2399
  identity: undefined,
@@ -2226,13 +2404,22 @@ async function effectiveConnectionStatus(runtime, options) {
2226
2404
  }
2227
2405
  async function inspectMcpEditor(runtime, options) {
2228
2406
  const inspected = await runtime.inspectEditor();
2407
+ const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
2408
+ const buildAlignment = assessBuildAlignment(fingerprint, inspected.identity.buildFingerprint, options.validationCommit);
2409
+ if (options.requireBuildAlignment && buildAlignment.status !== "matched") {
2410
+ throw new Error(`FRAMEKIT_BUILD_ALIGNMENT_MISMATCH: ${buildAlignment.message}`);
2411
+ }
2229
2412
  const native = options.nativeEditor?.capabilities();
2230
- const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
2231
- const publishingMode = publishingAvailable
2413
+ const processMode = options.processMode ?? (native ? "headed" : "headless");
2414
+ const configuredPublisher = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
2415
+ const publisherExecutionMode = configuredPublisher
2232
2416
  ? (typeof options.projectPublisher?.executionMode === "function"
2233
2417
  ? options.projectPublisher.executionMode()
2234
2418
  : "headed-only")
2235
2419
  : "unavailable";
2420
+ const publishingAvailable = configuredPublisher && (publisherExecutionMode === "background-capable"
2421
+ || processMode === "headed");
2422
+ const publishingMode = publishingAvailable ? publisherExecutionMode : "unavailable";
2236
2423
  const exportAvailable = Boolean(options.videoExporter?.isAvailable());
2237
2424
  const backgroundExportAvailable = Boolean(options.backgroundRenderer?.isAvailable());
2238
2425
  const capabilities = withCapabilityFamilies({
@@ -2305,14 +2492,138 @@ async function inspectMcpEditor(runtime, options) {
2305
2492
  },
2306
2493
  preflight: {
2307
2494
  ...createCapabilityPreflight(inspected.identity, capabilities, {
2308
- processMode: options.processMode ?? (native ? "headed" : "headless"),
2495
+ processMode,
2309
2496
  nativeWrite: Boolean(native?.selectionEdit),
2310
2497
  }),
2311
- fingerprint: options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT,
2498
+ fingerprint,
2499
+ buildAlignment,
2500
+ nativeHandoffReadiness: createNativeHandoffReadiness(options.projectPublisher, buildAlignment),
2312
2501
  },
2313
2502
  ...(native ? { native } : {}),
2314
2503
  };
2315
2504
  }
2505
+ async function inspectNativeHandoffReadiness(runtime, options, publishJobId) {
2506
+ const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
2507
+ let extensionFingerprint;
2508
+ try {
2509
+ extensionFingerprint = (await runtime.inspectEditor()).identity.buildFingerprint;
2510
+ }
2511
+ catch {
2512
+ const status = await connectionStatus(options).catch(() => undefined);
2513
+ extensionFingerprint = status?.identity?.buildFingerprint;
2514
+ }
2515
+ const buildAlignment = assessBuildAlignment(fingerprint, extensionFingerprint, options.validationCommit);
2516
+ return createNativeHandoffReadiness(options.projectPublisher, buildAlignment, publishJobId);
2517
+ }
2518
+ function createNativeHandoffReadiness(publisher, buildAlignment, publishJobId) {
2519
+ const publisherReadiness = inspectProjectPublisherReadiness(publisher);
2520
+ const reasons = [...publisherReadiness.reasons];
2521
+ if (buildAlignment.status !== "matched") {
2522
+ reasons.push({
2523
+ code: buildAlignment.status === "mismatched"
2524
+ ? "FRAMEKIT_BUILD_ALIGNMENT_MISMATCH"
2525
+ : "FRAMEKIT_BUILD_ALIGNMENT_MISSING",
2526
+ message: `Workflow Extension build alignment is ${buildAlignment.status}: ${buildAlignment.message}`,
2527
+ });
2528
+ }
2529
+ let publish;
2530
+ let verifiedTarget;
2531
+ if (publishJobId) {
2532
+ if (!publisher || typeof publisher.getPublishJob !== "function") {
2533
+ reasons.push({
2534
+ code: "FINAL_CUT_PUBLISH_JOB_UNAVAILABLE",
2535
+ message: `Publish job ${publishJobId} cannot be inspected because the publisher is unavailable`,
2536
+ });
2537
+ }
2538
+ else {
2539
+ try {
2540
+ const job = publisher.getPublishJob(publishJobId);
2541
+ publish = { jobId: job.jobId, state: job.state };
2542
+ const resultTarget = job.result?.createdTarget;
2543
+ const targetMatches = job.createdTarget
2544
+ && resultTarget
2545
+ && job.createdTarget.projectId === resultTarget.projectId
2546
+ && job.createdTarget.sequenceId === resultTarget.sequenceId;
2547
+ if (job.state === "verified" && job.result?.verified === true && targetMatches) {
2548
+ verifiedTarget = resultTarget;
2549
+ }
2550
+ else {
2551
+ reasons.push({
2552
+ code: "FINAL_CUT_PUBLISH_TARGET_UNVERIFIED",
2553
+ message: job.error?.message
2554
+ ? `Publish job ${job.jobId} is ${job.state}; native project and sequence IDs remain withheld: ${job.error.message}`
2555
+ : `Publish job ${job.jobId} is ${job.state}; native project and sequence IDs are reported only after native readback verifies them`,
2556
+ });
2557
+ }
2558
+ }
2559
+ catch (error) {
2560
+ const message = error instanceof Error ? error.message : String(error);
2561
+ reasons.push({
2562
+ code: "FINAL_CUT_PUBLISH_JOB_UNAVAILABLE",
2563
+ message: `Publish job ${publishJobId} could not be inspected: ${message}`,
2564
+ });
2565
+ }
2566
+ }
2567
+ }
2568
+ const ready = reasons.length === 0;
2569
+ return {
2570
+ status: ready ? (publishJobId ? "verified" : "ready") : "blocked",
2571
+ reasons,
2572
+ targetBinding: {
2573
+ available: publisherReadiness.targetBindingAvailable,
2574
+ guarantee: publisherReadiness.targetBindingAvailable ? "native-readback" : "none",
2575
+ },
2576
+ buildAlignment,
2577
+ ...(publish ? { publish } : {}),
2578
+ ...(ready && verifiedTarget ? { createdTarget: verifiedTarget } : {}),
2579
+ };
2580
+ }
2581
+ function inspectProjectPublisherReadiness(publisher) {
2582
+ if (!publisher) {
2583
+ return {
2584
+ available: false,
2585
+ targetBindingAvailable: false,
2586
+ reasons: [{
2587
+ code: "FINAL_CUT_PUBLISH_PROVIDER_UNAVAILABLE",
2588
+ message: "No Final Cut project publisher is configured",
2589
+ }],
2590
+ };
2591
+ }
2592
+ if (typeof publisher.inspectReadiness === "function")
2593
+ return publisher.inspectReadiness();
2594
+ // Keep older injected publisher implementations fail-closed but inspectable.
2595
+ const available = typeof publisher.isAvailable === "function" && publisher.isAvailable();
2596
+ return {
2597
+ available,
2598
+ targetBindingAvailable: available,
2599
+ reasons: available ? [] : [{
2600
+ code: "FINAL_CUT_PUBLISH_TARGET_BINDING_UNAVAILABLE",
2601
+ message: "Native publisher readiness or target-binding provider is unavailable",
2602
+ }],
2603
+ };
2604
+ }
2605
+ async function assertRequiredBuildAlignment(runtime, options) {
2606
+ const inspected = await runtime.inspectEditor();
2607
+ const fingerprint = options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT;
2608
+ const alignment = assessBuildAlignment(fingerprint, inspected.identity.buildFingerprint, options.validationCommit);
2609
+ if (alignment.status !== "matched") {
2610
+ throw new Error(`FRAMEKIT_BUILD_ALIGNMENT_MISMATCH: ${alignment.message}`);
2611
+ }
2612
+ }
2613
+ function withBuildAlignmentGuard(provider, assertAlignment, synchronousMethods = []) {
2614
+ const synchronous = new Set(synchronousMethods);
2615
+ return new Proxy(provider, {
2616
+ get(target, property) {
2617
+ const value = Reflect.get(target, property, target);
2618
+ if (typeof value !== "function" || synchronous.has(property))
2619
+ return value;
2620
+ return async (...args) => {
2621
+ await assertAlignment();
2622
+ return Reflect.apply(value, target, args);
2623
+ };
2624
+ },
2625
+ });
2626
+ }
2316
2627
  function requireArtifactTransaction(runtime, transactionId, artifactPath) {
2317
2628
  const transaction = runtime.getTransaction(transactionId);
2318
2629
  const target = transaction.target;
@@ -2334,6 +2645,9 @@ async function requireEditingRoute(runtime, options, operation, path, editType)
2334
2645
  throw new Error(`${route.reason.code}: ${route.reason.message}`);
2335
2646
  }
2336
2647
  }
2648
+ function requiresHeadedPublishingRoute(publisher) {
2649
+ return publisher.executionMode() !== "background-capable";
2650
+ }
2337
2651
  async function editingRouteContext(runtime, options) {
2338
2652
  const connection = await effectiveConnectionStatus(runtime, options);
2339
2653
  let nativeReadiness;
@@ -2355,18 +2669,19 @@ async function editingRouteContext(runtime, options) {
2355
2669
  return {
2356
2670
  connection,
2357
2671
  ...(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
- } : {}),
2672
+ ...headlessRoutingContext(options),
2369
2673
  ...(options.nativeEditor ? { native: { ...options.nativeEditor.capabilities() } } : {}),
2370
2674
  ...(nativeReadiness ? { nativeReadiness } : {}),
2371
2675
  };
2372
2676
  }
2677
+ function headlessRoutingContext(options) {
2678
+ return options.headlessProjects ? {
2679
+ headless: {
2680
+ available: true,
2681
+ backend: "framekit-project-store",
2682
+ guarantee: "canonical-write",
2683
+ // The legacy timeline.edit surface also includes unsupported operations.
2684
+ supportedOperations: HEADLESS_TIMELINE_EDIT_TYPES.map((editType) => `timeline.edit:${editType}`),
2685
+ },
2686
+ } : {};
2687
+ }
@@ -1,6 +1,7 @@
1
1
  import { readFileSync } from "node:fs";
2
2
  import { dirname, isAbsolute, join, resolve } from "node:path";
3
3
  import { fileURLToPath } from "node:url";
4
+ import { parsePackageBuildIdentity } from "./build-identity.js";
4
5
  const FRAMEKIT_PACKAGE_NAME = "@morshoto/framekit";
5
6
  export const FRAMEKIT_VERSION = readFramekitVersion();
6
7
  export const FRAMEKIT_BUILD_FINGERPRINT = Object.freeze({
@@ -38,8 +39,15 @@ function isMissingFile(error) {
38
39
  }
39
40
  function readFramekitCommit() {
40
41
  const configured = process.env.FRAMEKIT_BUILD_COMMIT?.trim();
41
- if (configured)
42
- return configured;
42
+ if (configured) {
43
+ if (!/^[0-9a-f]{40}$/i.test(configured)) {
44
+ throw new Error("FRAMEKIT_BUILD_COMMIT_INVALID: expected a full commit SHA");
45
+ }
46
+ return configured.toLowerCase();
47
+ }
48
+ const packaged = readPackageBuildIdentity();
49
+ if (packaged)
50
+ return packaged.commit;
43
51
  const repositoryRoot = findRepositoryRoot(dirname(fileURLToPath(import.meta.url)));
44
52
  if (!repositoryRoot)
45
53
  return "unknown";
@@ -85,6 +93,17 @@ function readFramekitCommit() {
85
93
  }
86
94
  return "unknown";
87
95
  }
96
+ function readPackageBuildIdentity() {
97
+ try {
98
+ const identityPath = join(dirname(fileURLToPath(import.meta.url)), "build-identity.json");
99
+ return parsePackageBuildIdentity(JSON.parse(readFileSync(identityPath, "utf8")), FRAMEKIT_VERSION);
100
+ }
101
+ catch (error) {
102
+ if (isMissingFile(error))
103
+ return undefined;
104
+ throw error;
105
+ }
106
+ }
88
107
  function findRepositoryRoot(start) {
89
108
  let directory = start;
90
109
  while (true) {