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