@morshoto/framekit 0.2.2 → 0.2.3

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 (156) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
  3. package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
  4. package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
  5. package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
  6. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
  7. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
  8. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
  9. package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
  10. package/dist-package/adapters/final-cut/typescript/src/canonical.js +33 -1
  11. package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
  12. package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
  13. package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
  14. package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
  15. package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
  16. package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
  17. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
  18. package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
  19. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +6 -1
  20. package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
  21. package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
  22. package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
  23. package/dist-package/adapters/final-cut/typescript/src/live.js +8 -0
  24. package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
  25. package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
  26. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
  27. package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
  28. package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
  29. package/dist-package/adapters/final-cut/typescript/src/native.js +274 -107
  30. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
  31. package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
  32. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +18 -2
  33. package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
  34. package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
  35. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
  36. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
  37. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
  38. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
  39. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
  40. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
  41. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +28 -4
  42. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
  43. package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
  44. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
  45. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
  46. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +25 -0
  47. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +5 -0
  48. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  49. package/dist-package/adapters/headless/typescript/src/index.d.ts +3 -0
  50. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  51. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  52. package/dist-package/apps/cli/src/main.d.ts +10 -0
  53. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  54. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +92 -2
  55. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  56. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  57. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  58. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  59. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  60. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  61. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  62. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  63. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  64. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  65. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  66. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  67. package/dist-package/apps/mcp-server/src/server.js +77 -7
  68. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  69. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  70. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  71. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  72. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  73. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  74. package/dist-package/packages/headless-application/src/headless-projects.d.ts +233 -0
  75. package/dist-package/packages/headless-application/src/headless-projects.js +1 -1
  76. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  77. package/dist-package/packages/headless-application/src/index.js +1 -0
  78. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  79. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  80. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  81. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  82. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  83. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  84. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  85. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  86. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  87. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  88. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  89. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  90. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  91. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  92. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  93. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  94. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  95. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  96. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  97. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  98. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  99. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  100. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  101. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  102. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  103. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  104. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  105. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  106. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  107. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  108. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  109. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  110. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  111. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  112. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  113. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  114. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  115. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  116. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  117. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  118. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  119. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  120. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  121. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  122. package/dist-package/packages/runtime/src/index.js +1 -0
  123. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  124. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  125. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  126. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  127. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  128. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  129. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  130. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  131. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  132. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  133. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  134. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  135. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  136. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  137. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  138. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  139. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  140. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  141. package/dist-package/packages/runtime/src/timeline/editing-session.js +32 -2
  142. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  143. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  144. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  145. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  146. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  147. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  148. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  149. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  150. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  151. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  152. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  153. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  154. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  155. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  156. package/package.json +17 -12
@@ -0,0 +1,18 @@
1
+ import type { EditingSessionState } from "../../../packages/runtime/src/index.js";
2
+ export type TimelineReadbackRoute = "session" | "fast-observation" | "canonical-resync";
3
+ export interface TimelineReadbackRequest {
4
+ hasCanonicalBase: boolean;
5
+ requestedCanonical: boolean;
6
+ finalVerification: boolean;
7
+ sessionState: EditingSessionState;
8
+ fastObservation?: {
9
+ available: boolean;
10
+ coverageComplete: boolean;
11
+ status: "unchanged" | "advanced-by-framekit" | "proven-structural-delta" | "possibly-stale" | "conflicted" | "canonical-resync-required" | "target-mismatch" | "provider-incompatible" | "unavailable";
12
+ };
13
+ }
14
+ export interface TimelineReadbackDecision {
15
+ route: TimelineReadbackRoute;
16
+ reason: string;
17
+ }
18
+ export declare function chooseTimelineReadback(request: TimelineReadbackRequest): TimelineReadbackDecision;
@@ -0,0 +1,90 @@
1
+ import type { CapabilityGuarantee, EditorIdentity, RuntimeCapabilities } from "../../../packages/runtime/src/index.js";
2
+ export type EditingRouteOperation = "project.list" | "project.select" | "project.inspect" | "timeline.inspect" | "editor.live.inspect" | "timeline.edit" | "timeline.mask.add" | "editor.native.edit" | "editor.native.picture-in-picture" | "artifact.edit" | "timeline.publish.new-project" | "timeline.export";
3
+ export type EditingRouteFallback = "none" | "external-renderer";
4
+ export type CapabilityUnavailableCategory = "background-api" | "canonical-snapshot" | "native-ui";
5
+ export declare const HEADLESS_TIMELINE_EDIT_TYPES: readonly ["insert-occurrence", "rename-occurrence", "trim-occurrence", "move-occurrence", "split-occurrence", "set-gain", "set-transform", "remove-occurrence", "add-marker", "add-title", "remove-title", "add-transition", "remove-transition"];
6
+ export declare const EDITING_ROUTE_EDIT_TYPES: readonly ["insert-occurrence", "rename-occurrence", "trim-occurrence", "move-occurrence", "split-occurrence", "set-gain", "set-transform", "remove-occurrence", "add-marker", "add-title", "remove-title", "add-transition", "remove-transition", "rename-clip", "trim-clip", "reduce-noise", "set-color-correction", "ripple-delete"];
7
+ export type EditingRouteEditType = (typeof EDITING_ROUTE_EDIT_TYPES)[number];
8
+ export interface EditingRouteRequest {
9
+ operation: EditingRouteOperation;
10
+ fallback?: EditingRouteFallback;
11
+ /** Select the headless SSoT or explicitly opt into a headed editor path. */
12
+ path?: "headless" | "headed";
13
+ /** Identify the concrete timeline edit for capability-granular headless routing. */
14
+ editType?: EditingRouteEditType;
15
+ }
16
+ export interface EditorRoutingContext {
17
+ connection: {
18
+ state: string;
19
+ lastError?: {
20
+ code: string;
21
+ message: string;
22
+ };
23
+ };
24
+ editor?: {
25
+ identity: EditorIdentity;
26
+ capabilities: RuntimeCapabilities;
27
+ };
28
+ native?: Record<string, boolean>;
29
+ nativeReadiness?: NativeRoutingReadiness;
30
+ headless?: {
31
+ available: boolean;
32
+ backend: string;
33
+ guarantee: CapabilityGuarantee;
34
+ supportedOperations: string[];
35
+ };
36
+ }
37
+ export interface NativeRoutingReadiness {
38
+ state: "ready" | "unavailable" | "timeout" | "cancelled" | "stale";
39
+ nextAction: "none" | "retry" | "queue" | "unavailable";
40
+ retryable: boolean;
41
+ firstMissing?: string;
42
+ frontmost: boolean;
43
+ timelineFocus: boolean;
44
+ selectedTarget: boolean;
45
+ targetKind?: "selected-clip" | "browser-media" | "playhead" | "unknown" | "none";
46
+ targetBound?: boolean;
47
+ overlay: "clear" | "blocked" | "unknown";
48
+ permission: "granted" | "required" | "unknown";
49
+ guidance: string;
50
+ undo: "available" | "unavailable" | "unknown";
51
+ }
52
+ export interface EditingRouteProvider {
53
+ backend: string;
54
+ guarantee: CapabilityGuarantee;
55
+ }
56
+ export interface EditingRouteReason {
57
+ code: "EDITOR_SELECTED" | "EDITOR_UNAVAILABLE" | "CAPABILITY_UNAVAILABLE" | "EXTERNAL_FALLBACK_SELECTED" | "HEADLESS_SELECTED" | "HEADLESS_UNAVAILABLE";
58
+ message: string;
59
+ connectionState: string;
60
+ cause?: {
61
+ code: string;
62
+ message: string;
63
+ };
64
+ unavailable?: {
65
+ category: CapabilityUnavailableCategory;
66
+ capability: string;
67
+ backend: string;
68
+ guarantee: CapabilityGuarantee;
69
+ message: string;
70
+ };
71
+ }
72
+ export interface EditingRoute {
73
+ operation: EditingRouteOperation;
74
+ status: "editor-selected" | "headless-selected" | "external-fallback-selected" | "unavailable";
75
+ selectedPath: "editor" | "headless" | "artifact" | "background" | "native" | "external-renderer" | "none";
76
+ requiredCapabilities: string[];
77
+ missingCapabilities: string[];
78
+ provider?: EditingRouteProvider;
79
+ readiness?: Pick<NativeRoutingReadiness, "state" | "nextAction" | "retryable" | "firstMissing" | "targetKind" | "targetBound" | "guidance">;
80
+ editor?: EditorIdentity;
81
+ workflow: string[];
82
+ reason: EditingRouteReason;
83
+ }
84
+ export declare const EDITOR_FIRST_WORKFLOW: string[];
85
+ export declare const HEADLESS_FIRST_WORKFLOW: string[];
86
+ export declare const BACKGROUND_LIBRARY_WORKFLOW: string[];
87
+ export declare const BACKGROUND_ARTIFACT_WORKFLOW: string[];
88
+ export declare const EDITOR_FIRST_MCP_INSTRUCTIONS: string;
89
+ export declare const HEADLESS_FIRST_MCP_INSTRUCTIONS: string;
90
+ export declare function resolveEditingRoute(request: EditingRouteRequest, context: EditorRoutingContext): EditingRoute;
@@ -0,0 +1,75 @@
1
+ import type { SessionSqliteObservationProvider } from "./headless-sessions.js";
2
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3
+ import { AgentVideoRuntime, type CapabilityProcessMode, type CapabilityPreflight, type EditorIdentity } from "../../../packages/runtime/src/index.js";
4
+ import { type BackgroundRenderExportProvider, type DisposableNativeEditWorkflow, type FinalCutProjectPublishJobState, FinalCutProjectPublisher, type FileCanonicalRecoveryGuard, type FinalCutVideoExporter, type NativeFinalCutEditor, type NativeOperationSession } from "../../../adapters/final-cut/typescript/src/index.js";
5
+ import { type BuildAlignmentReport } from "./build-alignment.js";
6
+ import { type FramekitBuildFingerprint } from "./version.js";
7
+ import { type EditingSessionChangeSource } from "./headless-sessions.js";
8
+ import { type SessionMaterializationPublisher } from "./materialization-jobs.js";
9
+ import { type HeadlessProjectWorkflow } from "../../../packages/headless-application/src/index.js";
10
+ export type { SessionMaterializationPublisher } from "./materialization-jobs.js";
11
+ export interface McpConnectionStatus {
12
+ state: string;
13
+ lastError?: {
14
+ code: string;
15
+ message: string;
16
+ };
17
+ editorDetected?: boolean;
18
+ extensionInstalled?: boolean;
19
+ socketPath?: string | null;
20
+ identity?: EditorIdentity;
21
+ capabilities?: unknown;
22
+ preflight?: McpCapabilityPreflight;
23
+ }
24
+ export interface McpCapabilityPreflight extends CapabilityPreflight {
25
+ fingerprint: FramekitBuildFingerprint;
26
+ buildAlignment: BuildAlignmentReport;
27
+ nativeHandoffReadiness: NativeHandoffReadiness;
28
+ }
29
+ export interface NativeHandoffReadiness {
30
+ status: "ready" | "blocked" | "verified";
31
+ reasons: Array<{
32
+ code: string;
33
+ message: string;
34
+ }>;
35
+ targetBinding: {
36
+ available: boolean;
37
+ guarantee: "native-readback" | "none";
38
+ };
39
+ buildAlignment: BuildAlignmentReport;
40
+ publish?: {
41
+ jobId: string;
42
+ state: FinalCutProjectPublishJobState;
43
+ };
44
+ createdTarget?: {
45
+ kind: "editor.project";
46
+ projectId: string;
47
+ sequenceId: string;
48
+ libraryId?: string;
49
+ eventId?: string;
50
+ libraryPath?: string;
51
+ projectName: string;
52
+ sequenceName?: string;
53
+ };
54
+ }
55
+ export interface McpServerOptions {
56
+ processMode?: CapabilityProcessMode;
57
+ connectionStatus?: () => McpConnectionStatus | undefined | Promise<McpConnectionStatus | undefined>;
58
+ nativeEditor?: NativeFinalCutEditor;
59
+ disposableNative?: Pick<DisposableNativeEditWorkflow, "preview" | "execute" | "undo">;
60
+ nativeOperationSession?: Pick<NativeOperationSession, "submit" | "status" | "retry" | "cancel">;
61
+ projectPublisher?: FinalCutProjectPublisher;
62
+ canonicalRecovery?: Pick<FileCanonicalRecoveryGuard, "inspectVersioned" | "inspectNativeReservation" | "assertClear" | "beginNative"> & Partial<Pick<FileCanonicalRecoveryGuard, "inspectNativeRecoveryEvidence">>;
63
+ videoExporter?: FinalCutVideoExporter;
64
+ backgroundRenderer?: BackgroundRenderExportProvider;
65
+ buildFingerprint?: FramekitBuildFingerprint;
66
+ requireBuildAlignment?: boolean;
67
+ validationCommit?: string;
68
+ sessionDirectory?: string;
69
+ sessionChangeSource?: EditingSessionChangeSource;
70
+ sqliteObservationProvider?: SessionSqliteObservationProvider;
71
+ materializationDirectory?: string;
72
+ sessionMaterializationPublisher?: SessionMaterializationPublisher;
73
+ headlessProjects?: HeadlessProjectWorkflow;
74
+ }
75
+ export declare function createMcpServer(runtime: AgentVideoRuntime, options?: McpServerOptions): McpServer;
@@ -6,12 +6,13 @@ import { types as utilTypes } from "node:util";
6
6
  import { isAbsolute, resolve as resolvePath } from "node:path";
7
7
  import { z } from "zod/v3";
8
8
  import { canonicalSnapshotDigest, createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, createTimelineIrFromProjectSnapshot, } from "../../../packages/runtime/src/index.js";
9
- import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, nativeMediaSearchQueryError, FinalCutProjectPublisher, FinalCutNativeAutomationAdapter, disabledNativeFocusContext, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
9
+ import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, NativeFinalCutMediaImportError, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, nativeMediaSearchQueryError, FinalCutProjectPublisher, FinalCutNativeAutomationAdapter, disabledNativeFocusContext, serializeNativeFinalCutPartialMutationError, } from "../../../adapters/final-cut/typescript/src/index.js";
10
10
  import { BACKGROUND_ARTIFACT_WORKFLOW, EDITING_ROUTE_EDIT_TYPES, EDITOR_FIRST_MCP_INSTRUCTIONS, HEADLESS_TIMELINE_EDIT_TYPES, HEADLESS_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
11
11
  import { assessBuildAlignment } from "./build-alignment.js";
12
12
  import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
13
13
  import { EditingSessionRepository } from "./headless-sessions.js";
14
14
  import { SessionMaterializationJobs, } from "./materialization-jobs.js";
15
+ import { externalEditOperations, externalEditPlanDigest, verifyExternalEditExportable, } from "../../../packages/headless-application/src/index.js";
15
16
  import { projectSnapshotFromTimelineIr } from "./headless-project-snapshot.js";
16
17
  import { chooseTimelineReadback } from "./readback-policy.js";
17
18
  import { registerSkillTools, skillPreviewResult } from "./tools/skills/register.js";
@@ -24,6 +25,16 @@ const builtInNativeMethods = new Map(Reflect.ownKeys(FinalCutNativeAutomationAda
24
25
  const builtInMapGet = Map.prototype.get;
25
26
  const builtInMapSet = Map.prototype.set;
26
27
  const builtInMapHas = Map.prototype.has;
28
+ // Target identities are opaque: reject blank values without rewriting the
29
+ // caller's approval before the adapter compares it with the observed target.
30
+ const nativeImportTargetIdentity = z.string().min(1).refine((value) => value.trim().length > 0);
31
+ const nativeImportTargetSchema = z.object({
32
+ libraryId: nativeImportTargetIdentity,
33
+ eventId: nativeImportTargetIdentity,
34
+ projectId: nativeImportTargetIdentity,
35
+ sequenceId: nativeImportTargetIdentity,
36
+ revision: nativeImportTargetIdentity,
37
+ });
27
38
  const revisionValueSchema = z.object({
28
39
  id: z.string(),
29
40
  sequence: z.number().int().nonnegative(),
@@ -838,6 +849,9 @@ function frameResult(value) {
838
849
  };
839
850
  }
840
851
  export function createMcpServer(runtime, options = {}) {
852
+ // Inspect only inert descriptors before wrapping. Unknown providers remain
853
+ // guarded rather than being executed to determine whether dispatch is safe.
854
+ const builtinImportUnavailable = isBuiltinImportObservationUnavailable(options.nativeEditor);
841
855
  runtime.registerBuiltinSkills();
842
856
  if (options.requireBuildAlignment) {
843
857
  const assertAlignment = () => assertRequiredBuildAlignment(runtime, options);
@@ -1227,6 +1241,45 @@ export function createMcpServer(runtime, options = {}) {
1227
1241
  description: "Search one Framekit-owned project's registered media by ID, name, or source path without contacting Final Cut.",
1228
1242
  inputSchema: { projectId: z.string().min(1), query: z.string() },
1229
1243
  }, async ({ projectId, query }) => sessionResult(() => requireHeadlessProjects().searchMedia(projectId, query)));
1244
+ const externalEditSchema = z.object({
1245
+ schemaVersion: z.literal(1),
1246
+ clips: z.array(z.object({
1247
+ id: z.string().min(1), mediaId: z.string().min(1),
1248
+ sourceStartTime: rationalTimeSchema, durationTime: rationalTimeSchema,
1249
+ }).strict()).min(1),
1250
+ title: z.object({
1251
+ id: z.string().min(1), text: z.string().min(1),
1252
+ startTime: rationalTimeSchema, durationTime: rationalTimeSchema,
1253
+ }).strict(),
1254
+ music: z.object({
1255
+ id: z.string().min(1), mediaId: z.string().min(1), sourceStartTime: rationalTimeSchema,
1256
+ startTime: rationalTimeSchema, durationTime: rationalTimeSchema, gainDb: z.number().finite(),
1257
+ }).strict(),
1258
+ }).strict();
1259
+ server.registerTool("headless.edit-json.preview", {
1260
+ description: "Preview a versioned external edit against a Framekit project without mutation.",
1261
+ inputSchema: { projectId: z.string().min(1), sequenceId: z.string().min(1), expectedRevision: revisionValueSchema, edit: externalEditSchema },
1262
+ }, async ({ projectId, sequenceId, expectedRevision, edit }) => sessionResult(async () => {
1263
+ const service = requireHeadlessProjects();
1264
+ const project = await service.inspect(projectId);
1265
+ const operations = externalEditOperations(edit, project.timeline, expectedRevision);
1266
+ const preview = await service.previewEdit(projectId, { schemaVersion: 1, expectedRevision, operations }, sequenceId);
1267
+ verifyExternalEditExportable(preview.after.timeline);
1268
+ return { ...preview, planDigest: externalEditPlanDigest(preview.command) };
1269
+ }));
1270
+ server.registerTool("headless.edit-json.execute", {
1271
+ description: "Execute a versioned external edit against a Framekit project revision.",
1272
+ inputSchema: { projectId: z.string().min(1), sequenceId: z.string().min(1), expectedRevision: revisionValueSchema, edit: externalEditSchema, approved: z.literal(true), planDigest: z.string().regex(/^[a-f0-9]{64}$/) },
1273
+ }, async ({ projectId, sequenceId, expectedRevision, edit, planDigest }) => sessionResult(async () => {
1274
+ const service = requireHeadlessProjects();
1275
+ const project = await service.inspect(projectId);
1276
+ const operations = externalEditOperations(edit, project.timeline, expectedRevision);
1277
+ const preview = await service.previewEdit(projectId, { schemaVersion: 1, expectedRevision, operations }, sequenceId);
1278
+ verifyExternalEditExportable(preview.after.timeline);
1279
+ if (externalEditPlanDigest(preview.command) !== planDigest)
1280
+ throw new Error("EXTERNAL_EDIT_STALE_PREVIEW: approved edit does not match preview");
1281
+ return service.executeEdit(projectId, { schemaVersion: 1, expectedRevision, operations }, sequenceId);
1282
+ }));
1230
1283
  server.registerTool("headless.edit.preview", {
1231
1284
  description: "Preview supported Framekit Timeline IR edits without persisting or mutating the project.",
1232
1285
  inputSchema: {
@@ -1430,12 +1483,16 @@ export function createMcpServer(runtime, options = {}) {
1430
1483
  : { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
1431
1484
  server.registerTool("editor.native.media.import", {
1432
1485
  description: "Import one local video or audio file into the active Final Cut Browser and wait for a stable media handle.",
1433
- inputSchema: { path: z.string().min(1) },
1434
- }, async ({ path }, extra) => {
1486
+ inputSchema: { path: z.string().min(1), expectedImportTarget: nativeImportTargetSchema.optional() },
1487
+ }, async ({ path, expectedImportTarget }, extra) => {
1435
1488
  if (!options.nativeEditor)
1436
1489
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
1490
+ if (builtinImportUnavailable) {
1491
+ await options.canonicalRecovery?.assertClear();
1492
+ return nativeMediaImportErrorResult(new NativeFinalCutMediaImportError("CAPABILITY_UNAVAILABLE", "native media import requires independently observed original source binding", { stage: "pre-import-browser-discovery", elapsedMs: 0, stageElapsedMs: 0, partialImportPossible: false }));
1493
+ }
1437
1494
  try {
1438
- return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal }));
1495
+ return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal, ...(expectedImportTarget ? { expectedImportTarget } : {}) }));
1439
1496
  }
1440
1497
  catch (error) {
1441
1498
  return nativeMediaImportErrorResult(error);
@@ -1443,11 +1500,11 @@ export function createMcpServer(runtime, options = {}) {
1443
1500
  });
1444
1501
  server.registerTool("editor.native.media.directory.preview", {
1445
1502
  description: "Enumerate supported top-level video files in a local directory without mutating Final Cut and return an expiring import preview.",
1446
- inputSchema: { path: z.string().trim().min(1) },
1447
- }, async ({ path }, extra) => {
1503
+ inputSchema: { path: z.string().trim().min(1), expectedImportTarget: nativeImportTargetSchema.optional() },
1504
+ }, async ({ path, expectedImportTarget }, extra) => {
1448
1505
  if (!options.nativeEditor)
1449
1506
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
1450
- return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal }));
1507
+ return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal, ...(expectedImportTarget ? { expectedImportTarget } : {}) }));
1451
1508
  });
1452
1509
  server.registerTool("editor.native.media.directory.execute", {
1453
1510
  description: "Import every file from a directory preview after explicit confirmation and return per-file stable media handles or failures.",
@@ -1455,6 +1512,10 @@ export function createMcpServer(runtime, options = {}) {
1455
1512
  }, async ({ previewToken, confirm }, extra) => {
1456
1513
  if (!options.nativeEditor)
1457
1514
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
1515
+ if (builtinImportUnavailable) {
1516
+ await options.canonicalRecovery?.assertClear();
1517
+ return nativeMediaImportErrorResult(new NativeFinalCutMediaImportError("CAPABILITY_UNAVAILABLE", "native media import requires independently observed original source binding", { stage: "pre-import-browser-discovery", elapsedMs: 0, stageElapsedMs: 0, partialImportPossible: false }));
1518
+ }
1458
1519
  return jsonResult(await options.nativeEditor.executeImportMediaDirectory(previewToken, confirm, { signal: extra.signal }));
1459
1520
  });
1460
1521
  server.registerTool("editor.native.edit", {
@@ -3060,6 +3121,15 @@ function managedArtifactChanged(path, digest) {
3060
3121
  closeSync(fd);
3061
3122
  }
3062
3123
  }
3124
+ function isBuiltinImportObservationUnavailable(provider) {
3125
+ if (!provider || utilTypes.isProxy(provider) || Object.getPrototypeOf(provider) !== FinalCutNativeAutomationAdapter.prototype)
3126
+ return false;
3127
+ const observer = Object.getOwnPropertyDescriptor(provider, "importSourceObserver");
3128
+ if (!observer || !("value" in observer) || observer.value !== undefined)
3129
+ return false;
3130
+ return ["importMedia", "executeImportMediaDirectory", "capabilities"].every((key) => !Object.getOwnPropertyDescriptor(provider, key)
3131
+ && Object.getOwnPropertyDescriptor(FinalCutNativeAutomationAdapter.prototype, key)?.value === builtInNativeMethods.get(key));
3132
+ }
3063
3133
  function withRecoveryCheckpointGuard(provider, recovery, allowedMethods = [], reservedMethods = [], reservationKind = "native") {
3064
3134
  const allowed = new Set(allowedMethods);
3065
3135
  const reserved = new Set(reservedMethods);
@@ -0,0 +1,19 @@
1
+ import type { SkillToolMetadata } from "./metadata.js";
2
+ export interface ListedSkillTool {
3
+ name: string;
4
+ description?: string;
5
+ inputSchema: unknown;
6
+ }
7
+ export interface SkillToolCatalogEntry extends Omit<SkillToolMetadata, "inputSchema"> {
8
+ inputSchema: Readonly<Record<string, unknown>>;
9
+ }
10
+ export interface SkillToolCatalog {
11
+ schemaVersion: 1;
12
+ tools: SkillToolCatalogEntry[];
13
+ }
14
+ export interface SkillToolCatalogResult {
15
+ catalog: SkillToolCatalog;
16
+ errors: string[];
17
+ }
18
+ /** Combine the public tools/list contract with its explicitly declared family metadata. */
19
+ export declare function buildSkillToolCatalog(metadata: readonly unknown[], listedTools: readonly ListedSkillTool[]): SkillToolCatalogResult;
@@ -0,0 +1,37 @@
1
+ import { z } from "zod/v3";
2
+ export type SkillToolName = "skill.list" | "skill.inspect" | "skill.preview" | "skill.execute";
3
+ export type SkillToolMode = "fixture" | "headless" | "editor";
4
+ export type SkillToolEffect = "read" | "preview" | "write";
5
+ export type SkillToolOutputContract = "SkillInspection[]" | "SkillInspection" | "SkillPreview" | "SkillExecution";
6
+ export interface SkillToolMetadata {
7
+ name: SkillToolName;
8
+ description: string;
9
+ inputSchema: z.ZodRawShape;
10
+ outputContract: SkillToolOutputContract;
11
+ capabilityModes: readonly SkillToolMode[];
12
+ capabilities: readonly string[];
13
+ effect: SkillToolEffect;
14
+ approval: {
15
+ kind: "none";
16
+ required: false;
17
+ } | {
18
+ kind: "runtime-preview-token";
19
+ required: true;
20
+ };
21
+ errorCodes: readonly string[];
22
+ examples: readonly Readonly<Record<string, unknown>>[];
23
+ }
24
+ export declare const skillRevisionValueSchema: z.ZodObject<{
25
+ id: z.ZodString;
26
+ sequence: z.ZodNumber;
27
+ timestamp: z.ZodString;
28
+ }, "strip", z.ZodTypeAny, {
29
+ id: string;
30
+ sequence: number;
31
+ timestamp: string;
32
+ }, {
33
+ id: string;
34
+ sequence: number;
35
+ timestamp: string;
36
+ }>;
37
+ export declare const SKILL_TOOL_METADATA: readonly SkillToolMetadata[];
@@ -0,0 +1,11 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import type { AgentVideoRuntime, SkillPreview } from "../../../../../packages/runtime/src/index.js";
3
+ /** Runtime capability and availability resolution stays behind this injected port. */
4
+ export type SkillToolsRuntime = Pick<AgentVideoRuntime, "listSkillAvailability" | "inspectSkillAvailability" | "previewSkill" | "executeSkill">;
5
+ export declare function registerSkillTools(server: McpServer, runtime: SkillToolsRuntime): void;
6
+ export declare function skillPreviewResult(preview: SkillPreview): {
7
+ content: {
8
+ type: "text";
9
+ text: string;
10
+ }[];
11
+ };
@@ -0,0 +1,4 @@
1
+ import type { BuildFingerprint } from "../../../packages/runtime/src/index.js";
2
+ export declare const FRAMEKIT_VERSION: string;
3
+ export type FramekitBuildFingerprint = BuildFingerprint;
4
+ export declare const FRAMEKIT_BUILD_FINGERPRINT: FramekitBuildFingerprint;
@@ -0,0 +1,30 @@
1
+ import type { ContextRevision, ProjectEditCommand, RationalTime, TimelineIr, TimelineIrEditOperation } from "../../runtime/src/index.js";
2
+ export interface ExternalEdit {
3
+ schemaVersion: 1;
4
+ clips: Array<{
5
+ id: string;
6
+ mediaId: string;
7
+ sourceStartTime: RationalTime;
8
+ durationTime: RationalTime;
9
+ }>;
10
+ title: {
11
+ id: string;
12
+ text: string;
13
+ startTime: RationalTime;
14
+ durationTime: RationalTime;
15
+ };
16
+ music: {
17
+ id: string;
18
+ mediaId: string;
19
+ sourceStartTime: RationalTime;
20
+ startTime: RationalTime;
21
+ durationTime: RationalTime;
22
+ gainDb: number;
23
+ };
24
+ }
25
+ /** Convert the bounded interchange format to the existing project transaction operations. */
26
+ export declare function externalEditOperations(edit: ExternalEdit, timeline: TimelineIr, expectedRevision: ContextRevision): TimelineIrEditOperation[];
27
+ /** Check the actual compiler before a JSON edit can be committed. No artifact is written. */
28
+ export declare function verifyExternalEditExportable(timeline: TimelineIr): void;
29
+ /** Bind an approved preview to its target, base revision and translated operations. */
30
+ export declare function externalEditPlanDigest(command: ProjectEditCommand): string;
@@ -0,0 +1,72 @@
1
+ import { createHash } from "node:crypto";
2
+ import { compileTimelineIrToFcpxml } from "../../../adapters/final-cut/typescript/src/documents.js";
3
+ import { ProjectTransactionError } from "../../runtime/src/index.js";
4
+ /** Convert the bounded interchange format to the existing project transaction operations. */
5
+ export function externalEditOperations(edit, timeline, expectedRevision) {
6
+ if (timeline.revision.id !== expectedRevision.id || timeline.revision.sequence !== expectedRevision.sequence) {
7
+ throw new ProjectTransactionError("PROJECT_EDIT_STALE_REVISION", "expected project revision does not match the inspected project", {
8
+ expectedRevision, actualRevision: timeline.revision,
9
+ });
10
+ }
11
+ const sequence = timeline.sequence;
12
+ if (BigInt(sequence.durationTime.value) !== 0n || sequence.occurrences.length || sequence.storyElements.length
13
+ || sequence.markers.length || sequence.captions.length || sequence.titles?.length || sequence.transitions?.length) {
14
+ throw new Error("EXTERNAL_EDIT_INVALID: a new external edit requires an empty timeline");
15
+ }
16
+ const assertSource = (id, kind) => {
17
+ const resource = timeline.resources.find((item) => item.id === id);
18
+ if (!resource || resource.mediaKind !== kind || resource.sourceKind !== "local-file" || !resource.sourceDigest) {
19
+ throw new Error(`EXTERNAL_EDIT_INVALID: ${id} is not a registered ${kind} source`);
20
+ }
21
+ return resource;
22
+ };
23
+ const frame = timeline.sequence.frameDuration;
24
+ const aligned = (time, grid = frame, label = "sequence") => {
25
+ const numerator = BigInt(time.value) * BigInt(grid.timescale);
26
+ const denominator = BigInt(time.timescale) * BigInt(grid.value);
27
+ if (denominator <= 0n || numerator % denominator !== 0n)
28
+ throw new Error(`EXTERNAL_EDIT_INVALID: timing must align to the ${label} frame grid`);
29
+ };
30
+ for (const clip of edit.clips) {
31
+ const resource = assertSource(clip.mediaId, "video");
32
+ const stream = resource.metadata?.streams.find((item) => item.kind === "video");
33
+ const rate = stream?.frameRate;
34
+ if (!rate || BigInt(rate.value) <= 0n || BigInt(rate.timescale) <= 0n) {
35
+ throw new Error(`EXTERNAL_EDIT_INVALID: ${clip.mediaId} has no supported source frame rate`);
36
+ }
37
+ if (!stream?.sourceRange)
38
+ throw new Error(`EXTERNAL_EDIT_INVALID: ${clip.mediaId} has no verified video stream bounds; register the source in a new project`);
39
+ const addRationalTimes = (a, b) => ({ value: String(BigInt(a.value) * BigInt(b.timescale) + BigInt(b.value) * BigInt(a.timescale)), timescale: String(BigInt(a.timescale) * BigInt(b.timescale)) });
40
+ const compare = (a, b) => BigInt(a.value) * BigInt(b.timescale) - BigInt(b.value) * BigInt(a.timescale);
41
+ if (compare(clip.sourceStartTime, stream.sourceRange.start) < 0n || compare(addRationalTimes(clip.sourceStartTime, clip.durationTime), addRationalTimes(stream.sourceRange.start, stream.sourceRange.duration)) > 0n) {
42
+ throw new Error(`EXTERNAL_EDIT_INVALID: ${clip.mediaId} range exceeds video stream bounds`);
43
+ }
44
+ const sourceFrame = { value: rate.timescale, timescale: rate.value };
45
+ aligned(clip.sourceStartTime);
46
+ const sourceOffset = { value: String(BigInt(clip.sourceStartTime.value) * BigInt(stream.sourceRange.start.timescale) - BigInt(stream.sourceRange.start.value) * BigInt(clip.sourceStartTime.timescale)), timescale: String(BigInt(clip.sourceStartTime.timescale) * BigInt(stream.sourceRange.start.timescale)) };
47
+ aligned(sourceOffset, sourceFrame, "source");
48
+ aligned(clip.durationTime);
49
+ aligned(clip.durationTime, sourceFrame, "source");
50
+ }
51
+ assertSource(edit.music.mediaId, "audio");
52
+ for (const time of [edit.music.sourceStartTime, edit.music.startTime, edit.music.durationTime, edit.title.startTime, edit.title.durationTime])
53
+ aligned(time);
54
+ return [
55
+ ...edit.clips.map((clip) => ({ type: "insert-occurrence", placement: "append", occurrence: {
56
+ ...clip, name: clip.id, startTime: { value: "0", timescale: "1" }, track: 0, role: "video",
57
+ } })),
58
+ { type: "insert-occurrence", occurrence: { ...edit.music, name: edit.music.id, track: 1, role: "music" } },
59
+ { type: "add-title", title: { ...edit.title, lane: 1 } },
60
+ ];
61
+ }
62
+ /** Check the actual compiler before a JSON edit can be committed. No artifact is written. */
63
+ export function verifyExternalEditExportable(timeline) {
64
+ compileTimelineIrToFcpxml(timeline, { target: {
65
+ provider: "final-cut", libraryUid: "preview-library", eventUid: "preview-event",
66
+ projectUid: "preview-project", sequenceUid: "preview-sequence", materialization: "versioned",
67
+ } });
68
+ }
69
+ /** Bind an approved preview to its target, base revision and translated operations. */
70
+ export function externalEditPlanDigest(command) {
71
+ return createHash("sha256").update(JSON.stringify(command)).digest("hex");
72
+ }