@morshoto/framekit 0.2.2 → 0.2.4

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 (160) 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 +27 -0
  47. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +7 -2
  48. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.d.ts +28 -0
  49. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.js +120 -0
  50. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  51. package/dist-package/adapters/headless/typescript/src/index.d.ts +4 -0
  52. package/dist-package/adapters/headless/typescript/src/index.js +1 -0
  53. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  54. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  55. package/dist-package/apps/cli/src/main.d.ts +10 -0
  56. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  57. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +92 -2
  58. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  59. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  60. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  61. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  62. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  63. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  64. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  65. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  66. package/dist-package/apps/mcp-server/src/main.js +2 -1
  67. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  68. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  69. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  70. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  71. package/dist-package/apps/mcp-server/src/server.js +93 -9
  72. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  73. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  74. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  75. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  76. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  77. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  78. package/dist-package/packages/headless-application/src/headless-projects.d.ts +259 -0
  79. package/dist-package/packages/headless-application/src/headless-projects.js +15 -2
  80. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  81. package/dist-package/packages/headless-application/src/index.js +1 -0
  82. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  83. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  84. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  85. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  86. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  87. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  88. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  89. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  90. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  91. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  92. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  93. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  94. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  95. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  96. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  97. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  98. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  99. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  100. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  101. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  102. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  103. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  104. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  105. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  106. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  107. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  108. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  109. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  110. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  111. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  112. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  113. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  114. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  115. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  116. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  117. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  118. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  119. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  120. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  121. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  122. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  123. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  124. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  125. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  126. package/dist-package/packages/runtime/src/index.js +1 -0
  127. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  128. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  129. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  130. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  131. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  132. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  133. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  134. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  135. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  136. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  137. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  138. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  139. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  140. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  141. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  142. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  143. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  144. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  145. package/dist-package/packages/runtime/src/timeline/editing-session.js +32 -2
  146. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  147. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  148. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  149. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  150. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  151. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  152. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  153. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  154. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  155. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  156. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  157. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  158. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  159. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  160. package/package.json +17 -12
@@ -0,0 +1 @@
1
+ export {};
@@ -9,7 +9,7 @@ import { HeadlessProjectService } from "../../../packages/headless-application/s
9
9
  import { createMcpServer } from "./server.js";
10
10
  import { createCanonicalSessionChangeSource } from "./headless-sessions.js";
11
11
  import { createCanonicalNativeSnapshotReader } from "./canonical-native-snapshot.js";
12
- import { FfmpegMediaMetadataProbe, FfmpegRenderVerifier, FfmpegTimelineRenderer } from "../../../adapters/headless/typescript/src/index.js";
12
+ import { FfmpegMediaMetadataProbe, FfmpegRenderVerifier, FfmpegTimelineRenderer, FfmpegStoryboardRenderer } from "../../../adapters/headless/typescript/src/index.js";
13
13
  import { shouldConfigureFinalCutProjectPublisher } from "./final-cut-runtime-config.js";
14
14
  const fixture = new InMemoryEditorAdapter({
15
15
  projectId: "project-1",
@@ -190,6 +190,7 @@ const headlessProjects = new HeadlessProjectService({
190
190
  protectedStateDirectory: framekitStateDirectory,
191
191
  mediaProbe: new FfmpegMediaMetadataProbe(),
192
192
  renderer: new FfmpegTimelineRenderer(),
193
+ storyboard: new FfmpegStoryboardRenderer(),
193
194
  verifier: new FfmpegRenderVerifier(),
194
195
  });
195
196
  const disposableNative = liveMode && !headlessFinalCut && !fcpxmlPath && nativeEditor
@@ -0,0 +1,204 @@
1
+ import { type TimelineIr } from "../../../packages/runtime/src/index.js";
2
+ import { type FileCanonicalRecoveryGuard, type TimelineIrMaterializationCoverage, type TimelineIrMaterializationProvenance, type TimelineIrToFcpxmlResult, type TimelineIrToFcpxmlTarget } from "../../../adapters/final-cut/typescript/src/index.js";
3
+ import { EditingSessionRepository } from "./headless-sessions.js";
4
+ export interface SessionMaterializationPublishRequest {
5
+ jobId: string;
6
+ artifactPath: string;
7
+ artifactDigest: string;
8
+ target: TimelineIrToFcpxmlTarget;
9
+ destination: TimelineIrToFcpxmlResult["destination"];
10
+ collisionPolicy: "create-only";
11
+ desired: TimelineIr;
12
+ desiredDigest: string;
13
+ baseDigest: string;
14
+ baseRevision: TimelineIr["revision"];
15
+ coverage: TimelineIrMaterializationCoverage;
16
+ provenance: TimelineIrMaterializationProvenance;
17
+ }
18
+ export type MaterializationVerificationTier = "artifact" | "delivery" | "storage-observed" | "canonical-verified" | "interaction-required";
19
+ export type MaterializationDeliveryState = "background" | "activated" | "prompted" | "failed" | "interaction-required";
20
+ export interface MaterializationDeliveryEvidence {
21
+ state: MaterializationDeliveryState;
22
+ route: "background" | "headed" | "unknown";
23
+ }
24
+ export interface MaterializationStructuralDiff {
25
+ target: {
26
+ projectId: string;
27
+ sequenceId: string;
28
+ };
29
+ desiredDigest: string;
30
+ actualDigest: string;
31
+ changes: Array<{
32
+ path: string;
33
+ before?: unknown;
34
+ after?: unknown;
35
+ }>;
36
+ }
37
+ export interface MaterializationVerification {
38
+ tier: MaterializationVerificationTier;
39
+ status: "verified" | "blocked" | "failed";
40
+ artifactDigest: string;
41
+ desiredDigest: string;
42
+ reason?: string;
43
+ canonicalReadbackDigest?: string;
44
+ canonicalTarget?: {
45
+ libraryUid: string;
46
+ eventUid: string;
47
+ projectUid: string;
48
+ sequenceUid: string;
49
+ };
50
+ structuralDiff?: MaterializationStructuralDiff;
51
+ delivery?: MaterializationDeliveryEvidence;
52
+ }
53
+ export interface SessionMaterializationPublisher {
54
+ trackNativeDispatch?<T>(operation: () => Promise<T>, onDispatch: () => void): Promise<T>;
55
+ readCanonicalTarget?(request: {
56
+ target: {
57
+ libraryUid: string;
58
+ eventUid: string;
59
+ projectUid: string;
60
+ sequenceUid: string;
61
+ };
62
+ }): Promise<{
63
+ canonicalReadback: TimelineIr;
64
+ canonicalTarget: {
65
+ libraryUid: string;
66
+ eventUid: string;
67
+ projectUid: string;
68
+ sequenceUid: string;
69
+ };
70
+ delivery?: MaterializationDeliveryEvidence;
71
+ }>;
72
+ publish(request: SessionMaterializationPublishRequest): Promise<{
73
+ state: "completed";
74
+ canonicalReadback: TimelineIr;
75
+ canonicalTarget: {
76
+ libraryUid: string;
77
+ eventUid: string;
78
+ projectUid: string;
79
+ sequenceUid: string;
80
+ };
81
+ headedNativeVerified: boolean;
82
+ delivery?: MaterializationDeliveryEvidence;
83
+ } | {
84
+ state: "blocked";
85
+ code: string;
86
+ message: string;
87
+ retryable: boolean;
88
+ delivery?: MaterializationDeliveryEvidence;
89
+ }>;
90
+ }
91
+ export interface SessionMaterializationJob {
92
+ schemaVersion: 1 | 2;
93
+ jobId: string;
94
+ sessionId: string;
95
+ state: "blocked" | "publishing" | "completed" | "failed";
96
+ nextAction: "retry" | "status" | "none";
97
+ artifactPath: string;
98
+ artifactDigest: string;
99
+ target: TimelineIrToFcpxmlTarget;
100
+ destination: TimelineIrToFcpxmlResult["destination"];
101
+ desired: TimelineIr;
102
+ desiredDigest: string;
103
+ baseDigest: string;
104
+ baseRevision: TimelineIr["revision"];
105
+ coverage?: TimelineIrMaterializationCoverage;
106
+ provenance?: TimelineIrMaterializationProvenance;
107
+ verification?: MaterializationVerification;
108
+ continuation?: {
109
+ state: "canonical-resync-required" | "resynced";
110
+ reason: string;
111
+ sessionId?: string;
112
+ readbackDigest?: string;
113
+ changeSinceHandoff?: "changed" | "unchanged" | "unknown";
114
+ delivery?: MaterializationDeliveryEvidence;
115
+ };
116
+ sessionDigest: string;
117
+ claim?: {
118
+ id: string;
119
+ claimedAt: string;
120
+ };
121
+ recoveryReservation?: {
122
+ reservationId: string;
123
+ reason: "native-quiescence-unproven";
124
+ };
125
+ providerError?: {
126
+ code: string;
127
+ message: string;
128
+ retryable: boolean;
129
+ };
130
+ providerRequestPhase?: "dispatch-intent" | "returned";
131
+ evidence: {
132
+ artifact: {
133
+ verified: true;
134
+ format: "fcpxml";
135
+ digest: string;
136
+ };
137
+ providerRequested: boolean;
138
+ canonicalReadback: boolean;
139
+ headedNative: boolean;
140
+ };
141
+ error?: {
142
+ code: string;
143
+ message: string;
144
+ retryable: boolean;
145
+ };
146
+ }
147
+ export declare class SessionMaterializationJobs {
148
+ private readonly directory;
149
+ private readonly sessions;
150
+ private readonly publisher?;
151
+ private readonly recoveryGuard?;
152
+ constructor(directory: string, sessions: EditingSessionRepository, publisher?: SessionMaterializationPublisher | undefined, recoveryGuard?: Pick<FileCanonicalRecoveryGuard, "beginNative"> | undefined);
153
+ preview(sessionId: string, target: TimelineIrToFcpxmlTarget): Promise<{
154
+ sessionId: string;
155
+ mutating: boolean;
156
+ sessionState: import("../../../packages/runtime/src/index.js").EditingSessionState;
157
+ target: TimelineIrToFcpxmlTarget;
158
+ destination: {
159
+ mode: "versioned" | "reuse-existing";
160
+ projectUid: string;
161
+ sequenceUid: string;
162
+ projectName: string;
163
+ sequenceName: string;
164
+ };
165
+ collisionPolicy: string;
166
+ artifactDigest: string;
167
+ coverage: TimelineIrMaterializationCoverage;
168
+ provenance: TimelineIrMaterializationProvenance;
169
+ evidence: {
170
+ artifact: {
171
+ verified: boolean;
172
+ format: "fcpxml";
173
+ digest: string;
174
+ };
175
+ };
176
+ }>;
177
+ execute(sessionId: string, target: TimelineIrToFcpxmlTarget, confirm: boolean): Promise<SessionMaterializationJob>;
178
+ status(jobId: string): Promise<SessionMaterializationJob>;
179
+ retry(jobId: string): Promise<SessionMaterializationJob>;
180
+ resync(jobId: string, sessionId: string): Promise<{
181
+ jobId: string;
182
+ state: "resynced";
183
+ sessionId: string;
184
+ changeSinceHandoff: "changed" | "unchanged" | "unknown";
185
+ canonicalTarget: {
186
+ libraryUid: string;
187
+ eventUid: string;
188
+ projectUid: string;
189
+ sequenceUid: string;
190
+ };
191
+ readbackDigest: string;
192
+ document: import("../../../packages/runtime/src/index.js").EditingSessionDocument;
193
+ delivery?: MaterializationDeliveryEvidence | undefined;
194
+ }>;
195
+ private attempt;
196
+ private validateStagedJob;
197
+ private claim;
198
+ private release;
199
+ private fail;
200
+ private save;
201
+ private jobPath;
202
+ private claimPath;
203
+ private assertProvider;
204
+ }
@@ -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: {
@@ -1341,9 +1394,23 @@ export function createMcpServer(runtime, options = {}) {
1341
1394
  },
1342
1395
  }, async ({ projectId, sequenceId, expectedRevision, parameters }) => sessionResult(() => requireHeadlessProjects().render(projectId, sequenceId, parameters, expectedRevision)));
1343
1396
  server.registerTool("headless.rough-cut.preview", {
1344
- 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.",
1397
+ description: "Preview a semantic rough-cut plan and a bounded storyboard; the digest binds the plan and operations without mutating the timeline.",
1345
1398
  inputSchema: headlessRoughCutRequestSchema.shape,
1346
- }, async (request) => sessionResult(() => requireHeadlessProjects().previewRoughCut(request)));
1399
+ }, async (request, extra) => {
1400
+ try {
1401
+ const preview = await requireHeadlessProjects().previewRoughCut(request, extra.signal, true);
1402
+ if (!preview.storyboard)
1403
+ throw new Error("HEADLESS_STORYBOARD_UNAVAILABLE: storyboard renderer returned no image");
1404
+ const { data, mimeType, ...metadata } = preview.storyboard;
1405
+ return { content: [
1406
+ { type: "text", text: JSON.stringify({ ...preview, storyboard: { mimeType, ...metadata } }) },
1407
+ { type: "image", data, mimeType },
1408
+ ] };
1409
+ }
1410
+ catch (error) {
1411
+ return sessionResult(async () => { throw error; });
1412
+ }
1413
+ });
1347
1414
  server.registerTool("headless.rough-cut.execute", {
1348
1415
  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.",
1349
1416
  inputSchema: {
@@ -1430,12 +1497,16 @@ export function createMcpServer(runtime, options = {}) {
1430
1497
  : { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
1431
1498
  server.registerTool("editor.native.media.import", {
1432
1499
  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) => {
1500
+ inputSchema: { path: z.string().min(1), expectedImportTarget: nativeImportTargetSchema.optional() },
1501
+ }, async ({ path, expectedImportTarget }, extra) => {
1435
1502
  if (!options.nativeEditor)
1436
1503
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
1504
+ if (builtinImportUnavailable) {
1505
+ await options.canonicalRecovery?.assertClear();
1506
+ 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 }));
1507
+ }
1437
1508
  try {
1438
- return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal }));
1509
+ return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal, ...(expectedImportTarget ? { expectedImportTarget } : {}) }));
1439
1510
  }
1440
1511
  catch (error) {
1441
1512
  return nativeMediaImportErrorResult(error);
@@ -1443,11 +1514,11 @@ export function createMcpServer(runtime, options = {}) {
1443
1514
  });
1444
1515
  server.registerTool("editor.native.media.directory.preview", {
1445
1516
  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) => {
1517
+ inputSchema: { path: z.string().trim().min(1), expectedImportTarget: nativeImportTargetSchema.optional() },
1518
+ }, async ({ path, expectedImportTarget }, extra) => {
1448
1519
  if (!options.nativeEditor)
1449
1520
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
1450
- return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal }));
1521
+ return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal, ...(expectedImportTarget ? { expectedImportTarget } : {}) }));
1451
1522
  });
1452
1523
  server.registerTool("editor.native.media.directory.execute", {
1453
1524
  description: "Import every file from a directory preview after explicit confirmation and return per-file stable media handles or failures.",
@@ -1455,6 +1526,10 @@ export function createMcpServer(runtime, options = {}) {
1455
1526
  }, async ({ previewToken, confirm }, extra) => {
1456
1527
  if (!options.nativeEditor)
1457
1528
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
1529
+ if (builtinImportUnavailable) {
1530
+ await options.canonicalRecovery?.assertClear();
1531
+ 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 }));
1532
+ }
1458
1533
  return jsonResult(await options.nativeEditor.executeImportMediaDirectory(previewToken, confirm, { signal: extra.signal }));
1459
1534
  });
1460
1535
  server.registerTool("editor.native.edit", {
@@ -3060,6 +3135,15 @@ function managedArtifactChanged(path, digest) {
3060
3135
  closeSync(fd);
3061
3136
  }
3062
3137
  }
3138
+ function isBuiltinImportObservationUnavailable(provider) {
3139
+ if (!provider || utilTypes.isProxy(provider) || Object.getPrototypeOf(provider) !== FinalCutNativeAutomationAdapter.prototype)
3140
+ return false;
3141
+ const observer = Object.getOwnPropertyDescriptor(provider, "importSourceObserver");
3142
+ if (!observer || !("value" in observer) || observer.value !== undefined)
3143
+ return false;
3144
+ return ["importMedia", "executeImportMediaDirectory", "capabilities"].every((key) => !Object.getOwnPropertyDescriptor(provider, key)
3145
+ && Object.getOwnPropertyDescriptor(FinalCutNativeAutomationAdapter.prototype, key)?.value === builtInNativeMethods.get(key));
3146
+ }
3063
3147
  function withRecoveryCheckpointGuard(provider, recovery, allowedMethods = [], reservedMethods = [], reservationKind = "native") {
3064
3148
  const allowed = new Set(allowedMethods);
3065
3149
  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
+ };