@machinal/mcp 0.6.0 → 0.6.1
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/README.md +21 -4
- package/library/guides/brief.md +3 -1
- package/library/guides/client-bootstrap.md +3 -3
- package/library/manifest.json +7 -7
- package/library/skills/machinal-editing.md +2 -0
- package/package.json +1 -1
- package/skills/machinal-editing/SKILL.md +2 -0
- package/skills/machinal-editing/references/brief.md +3 -1
- package/src/opencode-library.mjs +1 -1
- package/src/opencode-recipes.mjs +7 -5
- package/src/opencode-workflow.mjs +29 -4
- package/src/scene-library.mjs +39 -3
package/README.md
CHANGED
|
@@ -19,6 +19,10 @@ the same client-owned components.
|
|
|
19
19
|
`get_hyperframes_source` on the Machinal adapter.
|
|
20
20
|
- Catalog/source reads work offline without a key. Exact IDs load source;
|
|
21
21
|
discovery stays paginated. Files are pinned by the library manifest.
|
|
22
|
+
- For an animated treatment, search with `topic: "component-discovery"` and an
|
|
23
|
+
action query such as `"kinetic type"`. The default response ranks two native
|
|
24
|
+
candidates without source payloads. Pass the selected result's `source` back
|
|
25
|
+
to the library to open its exact Svelte template.
|
|
22
26
|
- Legacy `get_editing_reference` authoring calls and resource URIs are served
|
|
23
27
|
locally by the adapter/OpenCode companion. The direct API returns only a
|
|
24
28
|
compatibility notice for moved authoring guides, not the source.
|
|
@@ -28,6 +32,10 @@ the same client-owned components.
|
|
|
28
32
|
service and their normal permissions. Renderer modules and default runtime assets
|
|
29
33
|
stay in the service, not in the MCP package. Runtime imports must be compatible there.
|
|
30
34
|
Installing templates does not select local rendering or grant spending approval.
|
|
35
|
+
- OpenCode `compile_scene` accepts either `component` (inline Svelte) or
|
|
36
|
+
`componentFile` (an absolute local `.svelte` path). The companion reads the
|
|
37
|
+
file with host permission and passes its content to the original tool.
|
|
38
|
+
`sourceFile` still names an existing server scene being edited.
|
|
31
39
|
|
|
32
40
|
`npm run build:library` and `npm run sync:reference` operate entirely within
|
|
33
41
|
this package; they do not read authoring files from the API tree. Maintainers can
|
|
@@ -42,6 +50,15 @@ unpublished checkout changes automatically.
|
|
|
42
50
|
|
|
43
51
|
### Version 0.5.1: bounded concurrency and recipe diagnostics
|
|
44
52
|
|
|
53
|
+
### Version 0.6.1: guided component discovery and safer scene authoring
|
|
54
|
+
|
|
55
|
+
Adds offline action-based discovery for native scene templates and Hyperframes components, asks explicitly about sound effects when the brief leaves that choice open, and lets OpenCode compile a local `.svelte` file through the normal host permission flow. Improves library response compatibility and packages the complete client-owned authoring library. This npm release does not deploy the API or change existing installations; run `machinal setup` after upgrading to refresh the installed companion.
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
npm install -g @machinal/mcp@0.6.1
|
|
59
|
+
machinal setup
|
|
60
|
+
```
|
|
61
|
+
|
|
45
62
|
Version 0.5.1 adds separate adapter lanes for 8 reads, 8 job waits, 4 other tool calls and 2 control calls, with bounded queues and cancellation rather than a shared eight-request rejection cap. No submitted paid call is retried. Backend independent media jobs default to 4 per process (`MACHINAL_MEDIA_CONCURRENCY=1..16`); this is separate from MCP requests and render workers. Updated APIs report parse failures before caption guards, add a bounded narration/caption text-difference report and return compact `get_project` summaries (`fullResult:true` for editing). The OpenCode companion reuses project IDs and original beat contracts from approved checkpoints. See [scope, limits and activation](../../docs/MCP.md#recipe-diagnostics-and-concurrency-hardening-source-changes). npm publication does not deploy the API backend.
|
|
46
63
|
|
|
47
64
|
### Version 0.5.0: animation crafts and sound library
|
|
@@ -74,7 +91,7 @@ The existing `machinal-mcp` binary and `key set` / `key delete` remain compatibl
|
|
|
74
91
|
|
|
75
92
|
### Upgrade or clean uninstall
|
|
76
93
|
|
|
77
|
-
For a normal upgrade, run `npm install -g @machinal/mcp@0.6.
|
|
94
|
+
For a normal upgrade, run `npm install -g @machinal/mcp@0.6.1`, then `machinal setup` from the project. OpenCode setup replaces old managed companion versions (including `0.4.3`) across the project, its ancestors, global config and recorded OpenCode installs in the same profile. It retains the saved key, endpoints, project media and unrelated settings. An npm install alone replaces only the CLI; it does not rewrite agent configurations.
|
|
78
95
|
|
|
79
96
|
For a full removal, including the saved key, use:
|
|
80
97
|
|
|
@@ -103,14 +120,14 @@ Local mode detects a saved profile and reuses a running backend. With permission
|
|
|
103
120
|
|
|
104
121
|
**Migration compatibility:** existing `dal_…` keys, `DIRECTION_API_KEY` / `DIRECTION_API_ORIGIN` environment variables, and the previous Windows Credential Manager entry continue to work. New setups use `mach_…`, `MACHINAL_API_KEY` / `MACHINAL_API_ORIGIN`, and `Machinal/mcp.MACHINAL_API_KEY`; when both environment names are set, `MACHINAL_API_KEY` takes precedence. New keys are issued with the `mach_` prefix.
|
|
105
122
|
|
|
106
|
-
**Version 0.6.
|
|
123
|
+
**Version 0.6.1:** install this release from the `@machinal` scope, then use the short command:
|
|
107
124
|
|
|
108
125
|
This release adds focused animation/sound skills and richer scene review guidance/templates, retaining native approved client-file uploads and language-independent video preparation. `machinal_prepare_video` loads editing/cinema startup skills; other crafts stay on demand, and scene compilation/final rendering are guarded until startup context is loaded. No keyword classifier, extra model call or automatic spending is introduced.
|
|
109
126
|
|
|
110
127
|
OpenCode compatibility: production startup accepts the V2 skill-list response (`{ location, data }`) and legacy arrays. If optional skill discovery fails or changes shape, it emits a sanitized warning instead of preventing session setup. Regression tests cover both response shapes and discovery failures; the release gate tests the packed artifact as well.
|
|
111
128
|
|
|
112
129
|
```sh
|
|
113
|
-
npm install -g @machinal/mcp@0.6.
|
|
130
|
+
npm install -g @machinal/mcp@0.6.1
|
|
114
131
|
machinal setup
|
|
115
132
|
# Machinal Server: no URL entry, only your Machinal key:
|
|
116
133
|
machinal setup --client opencode --mode server
|
|
@@ -456,7 +473,7 @@ Test the npm executable/tarball path without publishing:
|
|
|
456
473
|
```sh
|
|
457
474
|
npm pack --dry-run
|
|
458
475
|
npm pack
|
|
459
|
-
npm install -g ./machinal-mcp-0.6.
|
|
476
|
+
npm install -g ./machinal-mcp-0.6.1.tgz
|
|
460
477
|
machinal --help
|
|
461
478
|
```
|
|
462
479
|
|
package/library/guides/brief.md
CHANGED
|
@@ -14,7 +14,7 @@ Cover these unanswered choices, with a short follow-up only when needed:
|
|
|
14
14
|
- **Duration:** approximate length; treat requested or AI-proposed runtimes as estimates unless the user explicitly sets a hard duration cap. Preserve the full successful narration by default rather than asking again about a flexible target.
|
|
15
15
|
- **Destination, framing and output resolution:** where it will be watched, landscape/portrait/classic, and the preferred resolution. Aspect ratio is not resolution. Offer a sensible supported choice, such as portrait 1080p for a mobile video, without silently imposing it. Check the live schema and scene limits before promising a format or resolution.
|
|
16
16
|
- **Visual direction and materials:** existing footage/photos, a newly generated image, an animated scene or a deliberate mix; desired mood, reference style and anything to avoid. Knowing the topic does not authorize choosing all visuals on the user's behalf.
|
|
17
|
-
- **Audio and text:** spoken language, narration or original sound, subtitles
|
|
17
|
+
- **Audio and text:** spoken language, narration or original sound, and subtitles. In the **same native form**, ask a separate sound-effects question when the choice is missing: e.g. “Vrei efecte sonore sincronizate cu acțiunea?” with “Efecte discrete” and “Fără efecte”. Keep it independent of narration/captions and any licensed music choice. Do not make every narration option silently opt out of effects. Reuse an explicit choice, complete brief or delegated decision; narration alone does not authorize sound effects or music. Do not promise unsupported music generation.
|
|
18
18
|
|
|
19
19
|
When sound effects are requested or already approved, load `animation-skills/machinal-sound` alongside editing. Carry them into the production contract and real YAML audio tracks; mentioning Openverse or promising a sound is not implementation. Search permission is not named-source/licence/project-use permission. Ask only for that missing scope once exact sources are selected, then continue through import, metadata measurement and timeline placement within approval. Never silently deliver an effects-free substitute; report the precise blocker if the requested sound cannot be implemented.
|
|
20
20
|
|
|
@@ -83,6 +83,8 @@ Ask the user which direction they prefer before locking an undecided visual appr
|
|
|
83
83
|
|
|
84
84
|
Include the desired visual intensity in the style question when it is unknown: quiet/minimal, expressive editorial, or bold/cinematic. For an open creative brief, recommend an expressive, polished treatment with motivated accents rather than silently choosing the least animated option. For “more spectacular”, propose a subject-specific reveal, transformation or spatial action, not merely extra particles, glow or rapid cuts. Respect an explicitly quiet/minimal style and accessibility needs; no effect or scene quota.
|
|
85
85
|
|
|
86
|
+
For an agreed new animated treatment, search `get_library_reference(topic: component-discovery, query: ...)` (OpenCode: `machinal_library`) before writing the scene. Search for the visible action, such as `kinetic type` for a hook or `panel reveal` for a comparison, rather than a video title or unrelated template. Compare up to two relevant candidates and open the chosen exact `scene-templates` ID to read its Svelte, media slots and timing. If none fits, try one shorter query or author from scratch; no required component count and no extra user approval for implementation IDs. Do not repeat discovery for unchanged scenes. On older installs, use a targeted `scene-templates` or `hyperframes-components` lookup.
|
|
87
|
+
|
|
86
88
|
Read only the relevant editing/scene references once the direction is known. Summarize the agreed brief as a progress update, not an approval gate: type/goal, duration, aspect and resolution, visual sources/treatment, narration/captions/music/sound effects. Then start the next authorized action immediately. For narration-led work, proposed beat times remain provisional until the speech duration and cues are measured.
|
|
87
89
|
|
|
88
90
|
## Let finished narration set an approximate runtime
|
|
@@ -4,7 +4,7 @@ Permissions: media listing, named-source use/inspection, paid generation/renderi
|
|
|
4
4
|
|
|
5
5
|
Before new video work read get_workflow_preferences and get_editing_reference(topic=brief). Ask only missing goal/type, duration, aspect AND resolution, visuals and audio/captions in ONE native question form, then proceed with the agreed authorized scope. A complete brief, small edit or delegated choice skips redundant questions. Never add unrequested narration/captions/music/sound effects. Music generation is unsupported.
|
|
6
6
|
|
|
7
|
-
Requested sound effects: read animation-skills/machinal-sound; add approved YAML audio tracks or report a blocker.
|
|
7
|
+
When effects are undecided in an open brief, ask “sound effects or no sound effects?” as its own item in the same native form, independently of narration/captions and licensed music. Requested sound effects: read animation-skills/machinal-sound; add approved YAML audio tracks or report a blocker.
|
|
8
8
|
|
|
9
9
|
Fetch live schema/capabilities once per schemaHash; retain them and exact preset references. Use compact responses, local recipe/checkpoint files and sourceJobId for UNCHANGED continuation. Read only references needed now, concurrently when independent. Detailed workflow: machinal://recipes/guide; full optional policy reference: machinal://reference/workflow. Do not repeatedly load the entire library or catalog.
|
|
10
10
|
|
|
@@ -20,9 +20,9 @@ After timing, inspect captionContentReview against approved narration, especiall
|
|
|
20
20
|
|
|
21
21
|
Narration uses a timing-first submission: approved speech plus requested captions ONLY; wait, read resolved recipeYaml and measured timings, then add visuals without rerunning successful jobs. Before NEW TTS read list_speech_models and ask model choice in the same brief unless chosen/delegated; respect the exact model/language/compatible voice. For Romanian recommend Gemini 3.8 Flash, offer Flash-Lite; for English offer Kokoro, Flash-Lite and Flash. Approximate runtime follows successful measured narration; an explicit hard cap requires resolution.
|
|
22
22
|
|
|
23
|
-
Before scene code
|
|
23
|
+
Before new scene code, search the local library with topic=component-discovery using short terms for the intended visible action. Compare up to two relevant native results and read the chosen exact scene-templates source; if no fit after one refinement, write native Svelte instead. Do not force a component or ask approval for implementation IDs. Read production and scene-runtime; use focused animation skills and the exact film style as needed. The CURRENT client writes/repairs Svelte/SceneThree. OpenCode compile_scene accepts inline component or absolute local componentFile, not both. Preserve animation during repairs; no server-model fallback or local production renderer. Use approved images for complex subjects and keep layouts caption-safe. Compare exact source/YAML against the production contract; use plan_scene_review and consent-bound inspect_scene for diagnostic frames when available. No automatic paid preview loop or production-process labels.
|
|
24
24
|
|
|
25
|
-
Preflight the exact final YAML after every edit: validate_recipe, no errors/unresolved requirements before render_video; compile_recipe inspects normalized editorial/production evidence, not aesthetic approval. Preserve successful assets/audio/captions and compare baseline versions. Reuse the successful preflight until edited. Check transition overlap/source-time math in topic=yaml, never test syntax with paid rendering.
|
|
25
|
+
Preflight the exact final YAML after every edit: validate_recipe, no errors/unresolved requirements before render_video; compile_recipe inspects normalized editorial/production evidence, not aesthetic approval. For image.generate use an accepted ratio such as '9:16', not the output alias portrait. When generating images without a positive existing timeline, place at least one image with a positive duration to avoid a post-generation invalid_duration; reuse materialized assets from failed jobs before retrying. Preserve successful assets/audio/captions and compare baseline versions. Reuse the successful preflight until edited. Check transition overlap/source-time math in topic=yaml, never test syntax with paid rendering.
|
|
26
26
|
|
|
27
27
|
Use stable idempotencyKey and reviewed composition/caption guards. Uncertain paid submissions: recover the original job/outputs first; no automatic replay or new key. Use wait_for_job(timeoutSeconds=120) for the SAME job until completed/failed/cancelled; get_job is an immediate snapshot, not a polling loop. Read get_job_result once for resolved YAML/checkpoint. Progress=1/status lookup success is not job success; cloud publication must complete. ETA exists only when returned, never extrapolate weighted progress.
|
|
28
28
|
|
package/library/manifest.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"format": 1,
|
|
3
|
-
"version": "sha256:
|
|
3
|
+
"version": "sha256:a2864d9be14bb0dac31386142c67bbec3da5dae4940ed56b092eaaf801664a5a",
|
|
4
4
|
"files": {
|
|
5
5
|
"animation-skills/machinal-choreography.md": {
|
|
6
6
|
"bytes": 3449,
|
|
@@ -455,12 +455,12 @@
|
|
|
455
455
|
"sha256": "a7d922aa3184f9b33b503906d2989cf75c37cea64ba693aaf23dc807a2a4f5f9"
|
|
456
456
|
},
|
|
457
457
|
"guides/brief.md": {
|
|
458
|
-
"bytes":
|
|
459
|
-
"sha256": "
|
|
458
|
+
"bytes": 16460,
|
|
459
|
+
"sha256": "dc77cb7e32972b3cb134a38bb31385c6b52429b77048ed638f67746c56d4ef50"
|
|
460
460
|
},
|
|
461
461
|
"guides/client-bootstrap.md": {
|
|
462
|
-
"bytes":
|
|
463
|
-
"sha256": "
|
|
462
|
+
"bytes": 7616,
|
|
463
|
+
"sha256": "06c9f0fd495bdbe3721bd0b5e204db5f321af3bf5b796fa489db230ae4816a77"
|
|
464
464
|
},
|
|
465
465
|
"guides/commands.md": {
|
|
466
466
|
"bytes": 4194,
|
|
@@ -13435,8 +13435,8 @@
|
|
|
13435
13435
|
"sha256": "d72ec78e93934f74d5e85cd382d3c0283e65609b3af543adede3c46198b8db90"
|
|
13436
13436
|
},
|
|
13437
13437
|
"skills/machinal-editing.md": {
|
|
13438
|
-
"bytes":
|
|
13439
|
-
"sha256": "
|
|
13438
|
+
"bytes": 15076,
|
|
13439
|
+
"sha256": "f42bb12ae7dd7a759ca4667da58561972036a40c0f97e0e70c4b4f0ab0da42a2"
|
|
13440
13440
|
},
|
|
13441
13441
|
"skills/machinal-hyperframes-cli.md": {
|
|
13442
13442
|
"bytes": 2505,
|
|
@@ -11,6 +11,8 @@ description: Clarify the video brief, integrate images with animated Svelte/Thre
|
|
|
11
11
|
|
|
12
12
|
**Requested sound effects must reach the mix.** Load `machinal-sound` alongside editing whenever sound effects are requested or already approved; do not wait for another request. Narration, music and sound effects are separate choices. Use `search_sound_effects`, approved exact-source/licence/project `import_sound_effect`, `get_asset_metadata` and real YAML audio tracks synchronized to visible actions. Search consent is not named-source use consent; ask only for genuinely missing permission and reuse covered approvals. Before final rendering compare every promised cue with actual returned assets, measured source ranges, timeline placement, nonzero clip/track gain, no mute and supported fades. Never silently deliver an effects-free substitute; report the precise source/licence/tool blocker. Metadata/import/preflight is not listening. Preserve successful narration, captions and unrelated audio.
|
|
13
13
|
|
|
14
|
+
If an open brief does not specify effects, include a separate “effects or no effects?” question in the same native form. For an agreed animated treatment, use local `component-discovery` with short action keywords; compare up to two candidates, read the chosen exact `scene-templates` source, and author from scratch if neither is suitable.
|
|
15
|
+
|
|
14
16
|
**Choose visual sources before procedural shortcuts.** For complex or overly simplistic SVG/CSS subjects, prefer approved image-backed scenes over token shapes. A documentary/biography may need 5–10 distinct images per video for people, geographic context, environments and period-grounded illustrations, not one repeated portrait with more labels. This is not a quota or cap; the four-image attachment limit is per scene, not per video. Read topic `scenes` for image coverage and tool selection: `generate_assets` creates approved `image.generate` artwork after the timing checkpoint, `compile_scene` composes/animates it. Do not simplify solely to make the video cheap; reuse suitable successful assets, respect the approved budget and no-generation/procedural-only constraints. This does not authorize unrelated narration, caption, pacing or transition changes.
|
|
15
17
|
|
|
16
18
|
**TikTok caption font.** When the brief targets TikTok or requests TikTok-style captions, NEW captions explicitly use `fontFamily: montserrat` and `fontWeight: 700`, unless the user explicitly chooses another font. Verify the deployed `fonts` entry; Montserrat is the supported TikTok-style choice, not official TikTok Sans. Set both fields in `captions.generate.style` before the timing-first pass, or flattened on newly authored manual captions; a `tiktok-pop`/`tiktok-box`/`tiktok-glow` preset name alone is not enough. Preserve existing caption fonts/configuration unless a font change is explicitly requested. Generic portrait/social output does not imply TikTok or authorize adding captions. Read `../machinal-recipes/references/text-audio.md`.
|
package/package.json
CHANGED
|
@@ -11,6 +11,8 @@ description: Clarify the video brief, integrate images with animated Svelte/Thre
|
|
|
11
11
|
|
|
12
12
|
**Requested sound effects must reach the mix.** Load `machinal-sound` alongside editing whenever sound effects are requested or already approved; do not wait for another request. Narration, music and sound effects are separate choices. Use `search_sound_effects`, approved exact-source/licence/project `import_sound_effect`, `get_asset_metadata` and real YAML audio tracks synchronized to visible actions. Search consent is not named-source use consent; ask only for genuinely missing permission and reuse covered approvals. Before final rendering compare every promised cue with actual returned assets, measured source ranges, timeline placement, nonzero clip/track gain, no mute and supported fades. Never silently deliver an effects-free substitute; report the precise source/licence/tool blocker. Metadata/import/preflight is not listening. Preserve successful narration, captions and unrelated audio.
|
|
13
13
|
|
|
14
|
+
If an open brief does not specify effects, include a separate “effects or no effects?” question in the same native form. For an agreed animated treatment, use local `component-discovery` with short action keywords; compare up to two candidates, read the chosen exact `scene-templates` source, and author from scratch if neither is suitable.
|
|
15
|
+
|
|
14
16
|
**Choose visual sources before procedural shortcuts.** For complex or overly simplistic SVG/CSS subjects, prefer approved image-backed scenes over token shapes. A documentary/biography may need 5–10 distinct images per video for people, geographic context, environments and period-grounded illustrations, not one repeated portrait with more labels. This is not a quota or cap; the four-image attachment limit is per scene, not per video. Read topic `scenes` for image coverage and tool selection: `generate_assets` creates approved `image.generate` artwork after the timing checkpoint, `compile_scene` composes/animates it. Do not simplify solely to make the video cheap; reuse suitable successful assets, respect the approved budget and no-generation/procedural-only constraints. This does not authorize unrelated narration, caption, pacing or transition changes.
|
|
15
17
|
|
|
16
18
|
**TikTok caption font.** When the brief targets TikTok or requests TikTok-style captions, NEW captions explicitly use `fontFamily: montserrat` and `fontWeight: 700`, unless the user explicitly chooses another font. Verify the deployed `fonts` entry; Montserrat is the supported TikTok-style choice, not official TikTok Sans. Set both fields in `captions.generate.style` before the timing-first pass, or flattened on newly authored manual captions; a `tiktok-pop`/`tiktok-box`/`tiktok-glow` preset name alone is not enough. Preserve existing caption fonts/configuration unless a font change is explicitly requested. Generic portrait/social output does not imply TikTok or authorize adding captions. Read `../machinal-recipes/references/text-audio.md`.
|
|
@@ -14,7 +14,7 @@ Cover these unanswered choices, with a short follow-up only when needed:
|
|
|
14
14
|
- **Duration:** approximate length; treat requested or AI-proposed runtimes as estimates unless the user explicitly sets a hard duration cap. Preserve the full successful narration by default rather than asking again about a flexible target.
|
|
15
15
|
- **Destination, framing and output resolution:** where it will be watched, landscape/portrait/classic, and the preferred resolution. Aspect ratio is not resolution. Offer a sensible supported choice, such as portrait 1080p for a mobile video, without silently imposing it. Check the live schema and scene limits before promising a format or resolution.
|
|
16
16
|
- **Visual direction and materials:** existing footage/photos, a newly generated image, an animated scene or a deliberate mix; desired mood, reference style and anything to avoid. Knowing the topic does not authorize choosing all visuals on the user's behalf.
|
|
17
|
-
- **Audio and text:** spoken language, narration or original sound, subtitles
|
|
17
|
+
- **Audio and text:** spoken language, narration or original sound, and subtitles. In the **same native form**, ask a separate sound-effects question when the choice is missing: e.g. “Vrei efecte sonore sincronizate cu acțiunea?” with “Efecte discrete” and “Fără efecte”. Keep it independent of narration/captions and any licensed music choice. Do not make every narration option silently opt out of effects. Reuse an explicit choice, complete brief or delegated decision; narration alone does not authorize sound effects or music. Do not promise unsupported music generation.
|
|
18
18
|
|
|
19
19
|
When sound effects are requested or already approved, load `animation-skills/machinal-sound` alongside editing. Carry them into the production contract and real YAML audio tracks; mentioning Openverse or promising a sound is not implementation. Search permission is not named-source/licence/project-use permission. Ask only for that missing scope once exact sources are selected, then continue through import, metadata measurement and timeline placement within approval. Never silently deliver an effects-free substitute; report the precise blocker if the requested sound cannot be implemented.
|
|
20
20
|
|
|
@@ -83,6 +83,8 @@ Ask the user which direction they prefer before locking an undecided visual appr
|
|
|
83
83
|
|
|
84
84
|
Include the desired visual intensity in the style question when it is unknown: quiet/minimal, expressive editorial, or bold/cinematic. For an open creative brief, recommend an expressive, polished treatment with motivated accents rather than silently choosing the least animated option. For “more spectacular”, propose a subject-specific reveal, transformation or spatial action, not merely extra particles, glow or rapid cuts. Respect an explicitly quiet/minimal style and accessibility needs; no effect or scene quota.
|
|
85
85
|
|
|
86
|
+
For an agreed new animated treatment, search `get_library_reference(topic: component-discovery, query: ...)` (OpenCode: `machinal_library`) before writing the scene. Search for the visible action, such as `kinetic type` for a hook or `panel reveal` for a comparison, rather than a video title or unrelated template. Compare up to two relevant candidates and open the chosen exact `scene-templates` ID to read its Svelte, media slots and timing. If none fits, try one shorter query or author from scratch; no required component count and no extra user approval for implementation IDs. Do not repeat discovery for unchanged scenes. On older installs, use a targeted `scene-templates` or `hyperframes-components` lookup.
|
|
87
|
+
|
|
86
88
|
Read only the relevant editing/scene references once the direction is known. Summarize the agreed brief as a progress update, not an approval gate: type/goal, duration, aspect and resolution, visual sources/treatment, narration/captions/music/sound effects. Then start the next authorized action immediately. For narration-led work, proposed beat times remain provisional until the speech duration and cues are measured.
|
|
87
89
|
|
|
88
90
|
## Let finished narration set an approximate runtime
|
package/src/opencode-library.mjs
CHANGED
|
@@ -12,7 +12,7 @@ export async function installSceneLibrary(ctx, servers = []) {
|
|
|
12
12
|
tool.execute = async (input, context) => {
|
|
13
13
|
if (!library.handles('get_editing_reference', input)) return original(input, context);
|
|
14
14
|
const result = await library.call('get_editing_reference', input);
|
|
15
|
-
return { content: JSON.stringify(result.structuredContent), ...(result.isError ? { isError: true } : {}) };
|
|
15
|
+
return { content: JSON.stringify(result.structuredContent), output: result.structuredContent, ...(result.isError ? { isError: true } : {}) };
|
|
16
16
|
};
|
|
17
17
|
});
|
|
18
18
|
}
|
package/src/opencode-recipes.mjs
CHANGED
|
@@ -20,15 +20,17 @@ export async function filePermission(ctx, context, action, path) {
|
|
|
20
20
|
});
|
|
21
21
|
}
|
|
22
22
|
|
|
23
|
-
export async function readBoundedUTF8(path, signal) {
|
|
23
|
+
export async function readBoundedUTF8(path, signal, maxBytes = maxRecipeBytes, label = 'Recipe') {
|
|
24
24
|
const info = await lstat(path);
|
|
25
|
-
|
|
25
|
+
const tooLarge = `${label} exceeds the ${maxBytes === maxRecipeBytes ? '2 MiB' : `${maxBytes} byte`} limit.`;
|
|
26
|
+
if (!info.isFile() || info.isSymbolicLink()) throw new Error(`${label} must be a regular file, not a symbolic link.`);
|
|
26
27
|
const file = await open(path, 'r');
|
|
27
28
|
try {
|
|
28
29
|
const actual = await file.stat();
|
|
29
|
-
if (!actual.isFile() || actual.
|
|
30
|
+
if (!actual.isFile() || actual.ino !== info.ino || actual.dev !== info.dev) throw new Error(`${label} changed before it could be read.`);
|
|
31
|
+
if (actual.size > maxBytes) throw new Error(tooLarge);
|
|
30
32
|
// Bound the read even if another process grows the file after stat.
|
|
31
|
-
const buffer = Buffer.alloc(
|
|
33
|
+
const buffer = Buffer.alloc(maxBytes + 1);
|
|
32
34
|
let length = 0;
|
|
33
35
|
while (length < buffer.length) {
|
|
34
36
|
signal?.throwIfAborted();
|
|
@@ -36,7 +38,7 @@ export async function readBoundedUTF8(path, signal) {
|
|
|
36
38
|
if (!bytesRead) break;
|
|
37
39
|
length += bytesRead;
|
|
38
40
|
}
|
|
39
|
-
if (length >
|
|
41
|
+
if (length > maxBytes) throw new Error(tooLarge);
|
|
40
42
|
return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buffer.subarray(0, length));
|
|
41
43
|
} finally { await file.close(); }
|
|
42
44
|
}
|
|
@@ -1,6 +1,13 @@
|
|
|
1
|
+
import { realpath } from 'node:fs/promises';
|
|
2
|
+
import { isAbsolute } from 'node:path';
|
|
3
|
+
import { filePermission, readBoundedUTF8 } from './opencode-recipes.mjs';
|
|
4
|
+
|
|
1
5
|
export const productionSkills = ['machinal-editing', 'machinal-recipes', 'machinal-scenes', 'machinal-cinema', 'machinal-review', 'machinal-credits', 'machinal-motion', 'machinal-choreography', 'machinal-spatial', 'machinal-visual-review', 'machinal-sound'];
|
|
2
6
|
export const startupSkills = ['machinal-editing', 'machinal-cinema'];
|
|
3
7
|
|
|
8
|
+
const briefAndComponents = 'In an open video brief ask explicitly “sound effects or no sound effects?” in the same native form, separately from voice/captions and licensed music. Reuse explicit choices. Before writing a new animated treatment, search the local library with topic=component-discovery and short terms for the intended action. Compare up to two relevant native candidates; read the chosen exact scene-templates source. Do not force a component when none fits or ask the user to choose implementation IDs.';
|
|
9
|
+
const maxComponentBytes = 64000;
|
|
10
|
+
|
|
4
11
|
async function installedSkills(ctx) {
|
|
5
12
|
try {
|
|
6
13
|
const result = await ctx.skill.list();
|
|
@@ -39,7 +46,7 @@ export async function installWorkflowStartup(ctx, servers = []) {
|
|
|
39
46
|
await ctx.tool.transform(editor => {
|
|
40
47
|
editor.add({
|
|
41
48
|
name: 'machinal_prepare_video',
|
|
42
|
-
|
|
49
|
+
description: 'Start or resume video creation/editing in ANY language before the brief/media/production. Loads editing and cinema startup guidance; load recipe/scene/review/credit guides only for the current stage. Required before compile_scene/render_video. No provider calls, media access, jobs or spending. Not for MCP/code debugging or standalone images. Preparation is not production permission.',
|
|
43
50
|
input: { type: 'object', additionalProperties: false, required: ['purpose'], properties: {
|
|
44
51
|
purpose: { type: 'string', enum: ['create', 'edit'], description: 'The video task understood by the current agent, independent of the user’s language.' },
|
|
45
52
|
} },
|
|
@@ -59,7 +66,7 @@ export async function installWorkflowStartup(ctx, servers = []) {
|
|
|
59
66
|
prepared.set(context.sessionID, { skills, contextLoaded: false });
|
|
60
67
|
if (prepared.size > 128) prepared.delete(prepared.keys().next().value);
|
|
61
68
|
return { content: JSON.stringify({ status: 'ready', purpose: input.purpose, loadedSkills: startupSkills,
|
|
62
|
-
next:
|
|
69
|
+
next: `${briefAndComponents} Fetch stage-specific guides only as needed. Existing source/spending approvals remain separate; resume existing jobs/assets.` }) };
|
|
63
70
|
},
|
|
64
71
|
});
|
|
65
72
|
for (const server of names) {
|
|
@@ -67,16 +74,34 @@ export async function installWorkflowStartup(ctx, servers = []) {
|
|
|
67
74
|
editor.update(`${server}_${name}`.replace(/[^a-z\d_-]/gi, '_'), tool => {
|
|
68
75
|
const execute = tool.execute;
|
|
69
76
|
tool.description += ' Requires machinal_prepare_video in this session to load production guidance including cinema. Missing preparation executes no scene/render action.';
|
|
77
|
+
if (name === 'compile_scene') {
|
|
78
|
+
tool.input = { ...tool.input, required: (tool.input?.required ?? []).filter(key => key !== 'component'), properties: {
|
|
79
|
+
...tool.input?.properties,
|
|
80
|
+
componentFile: { type: 'string', description: 'Absolute client-local .svelte source (UTF-8, at most 64000 bytes). Use instead of inline component. Reads with host permission; attachments/sourceFile stay on the project server.' },
|
|
81
|
+
} };
|
|
82
|
+
tool.description += ' Supply exactly one of component or componentFile. Prefer componentFile for a saved Svelte scene; preserve the full artwork and motion when repairing diagnostics.';
|
|
83
|
+
}
|
|
70
84
|
tool.execute = async (input, context) => {
|
|
71
85
|
if (!prepared.get(context.sessionID)?.contextLoaded) return { content: JSON.stringify({ status: 'blocked', nextTool: 'machinal_prepare_video', error: 'Load video production guidance, including cinema, into the next model context before this action. Do not batch preparation and production in one model turn. No action was executed; no paid job was submitted.' }) };
|
|
72
|
-
return execute(input, context);
|
|
86
|
+
if (name !== 'compile_scene') return execute(input, context);
|
|
87
|
+
const { componentFile, ...args } = input;
|
|
88
|
+
if ((componentFile === undefined) === (args.component === undefined)) throw new Error('Supply exactly one of component (complete Svelte source) or componentFile (absolute .svelte path). No compilation started.');
|
|
89
|
+
if (componentFile !== undefined) {
|
|
90
|
+
if (typeof componentFile !== 'string' || !isAbsolute(componentFile) || !/\.svelte$/i.test(componentFile)) throw new Error('Use an absolute client-local .svelte path for componentFile.');
|
|
91
|
+
await filePermission(ctx, context, 'read', componentFile);
|
|
92
|
+
const canonical = await realpath(componentFile);
|
|
93
|
+
if (canonical !== componentFile) await filePermission(ctx, context, 'read', canonical);
|
|
94
|
+
args.component = await readBoundedUTF8(componentFile, context.signal, maxComponentBytes, 'Svelte source');
|
|
95
|
+
}
|
|
96
|
+
if (typeof args.component !== 'string' || !args.component.trim() || Buffer.byteLength(args.component) > maxComponentBytes) throw new Error('Svelte source must contain 1–64000 UTF-8 bytes and must not be blank. No compilation started.');
|
|
97
|
+
return execute(args, context);
|
|
73
98
|
};
|
|
74
99
|
});
|
|
75
100
|
}
|
|
76
101
|
}
|
|
77
102
|
});
|
|
78
103
|
await ctx.session.hook('context', event => {
|
|
79
|
-
event.system.push({ type: 'text', text:
|
|
104
|
+
event.system.push({ type: 'text', text: `machinal startup: the CURRENT agent understands video intent in any language. Call machinal_prepare_video before creating/editing video, not MCP/code debugging. Do not match keywords or use another classifier. Preparation loads editing/cinema only and grants no media/spending permission. ${briefAndComponents} Read/cache stage-specific guides and the exact chosen film-style source as needed. Resume saved recipes/jobs/assets after interruption; never submit duplicate paid work.` });
|
|
80
105
|
const state = prepared.get(event.sessionID);
|
|
81
106
|
for (const skill of state?.skills ?? []) {
|
|
82
107
|
event.system.push({ type: 'text', text: `<skill_content name="${skill.id}">\n${skill.content}\n\nSkill source: ${skill.path ?? 'installed skill registry'}\n</skill_content>` });
|
package/src/scene-library.mjs
CHANGED
|
@@ -13,7 +13,7 @@ const GUIDE_TOPICS = {
|
|
|
13
13
|
'animation-skills': 'animation-skills', 'film-styles': 'film-styles', 'film-techniques': 'film-styles',
|
|
14
14
|
'scene-templates': 'scene-templates',
|
|
15
15
|
};
|
|
16
|
-
export const LIBRARY_TOPICS = [...Object.keys(GUIDE_TOPICS), 'hyperframes-components', 'hyperframes-skills', 'hyperframes-files', 'hyperframes-native'];
|
|
16
|
+
export const LIBRARY_TOPICS = [...Object.keys(GUIDE_TOPICS), 'component-discovery', 'hyperframes-components', 'hyperframes-skills', 'hyperframes-files', 'hyperframes-native'];
|
|
17
17
|
const MAX_SOURCE_BYTES = 4 * 1024 * 1024;
|
|
18
18
|
const CHUNK_BYTES = 48 * 1024;
|
|
19
19
|
const CATALOGS = {
|
|
@@ -37,14 +37,14 @@ export const LIBRARY_SCHEMA = {
|
|
|
37
37
|
properties: {
|
|
38
38
|
topic: { type: 'string', enum: LIBRARY_TOPICS },
|
|
39
39
|
id: { type: 'string', maxLength: 128 },
|
|
40
|
-
query: { type: 'string', maxLength: 80 },
|
|
40
|
+
query: { type: 'string', maxLength: 80, description: 'Literal substring, except component-discovery: short motion/visual terms (e.g. "kinetic type", "panel reveal"), ranked across native scene templates and Hyperframes.' },
|
|
41
41
|
offset: { type: 'integer', minimum: 0 },
|
|
42
42
|
limit: { type: 'integer', minimum: 1, maximum: 25 },
|
|
43
43
|
includeGuide: { type: 'boolean' },
|
|
44
44
|
},
|
|
45
45
|
};
|
|
46
46
|
export const LIBRARY_TOOLS = [
|
|
47
|
-
{ name: 'get_library_reference', description: 'Read the installed scene/Hyperframes library
|
|
47
|
+
{ name: 'get_library_reference', description: 'Read the installed scene/Hyperframes library offline. For a new animated treatment, start with topic=component-discovery and a short query describing the action; get two ranked native candidates by default. Read the chosen source with topic=scene-templates and its exact template ID. Compilation/rendering still use the configured renderer. Not permission for media use or paid work.',
|
|
48
48
|
inputSchema: LIBRARY_SCHEMA, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false } },
|
|
49
49
|
{ name: 'get_hyperframes_source', description: 'Read an installed, pinned Hyperframes source by a discovered file ID. UTF-8 byte chunks, up to 48 KiB; continue with sourceNextOffset. No execution, user-media access or spending.',
|
|
50
50
|
inputSchema: { type: 'object', required: ['id'], properties: { id: { type: 'string', maxLength: 128 }, offset: { type: 'integer', minimum: 0 } }, additionalProperties: false },
|
|
@@ -60,6 +60,10 @@ function validateInput(input) {
|
|
|
60
60
|
|| input.includeGuide !== undefined && typeof input.includeGuide !== 'boolean') throw new Error('Use a supported local library topic and valid ID/query/pagination.');
|
|
61
61
|
}
|
|
62
62
|
|
|
63
|
+
function searchWords(text) {
|
|
64
|
+
return text.toLowerCase().normalize('NFD').replace(/\p{M}/gu, '').match(/[\p{L}\p{N}]+/gu) ?? [];
|
|
65
|
+
}
|
|
66
|
+
|
|
63
67
|
export class SceneLibrary {
|
|
64
68
|
constructor(root = LIBRARY_ROOT) {
|
|
65
69
|
this.root = root;
|
|
@@ -128,8 +132,40 @@ export class SceneLibrary {
|
|
|
128
132
|
return this.original(entry, input.offset ?? 0);
|
|
129
133
|
}
|
|
130
134
|
|
|
135
|
+
async discoverComponents(input) {
|
|
136
|
+
const terms = searchWords(input.query ?? '');
|
|
137
|
+
if (!terms.length || input.id !== undefined) throw new Error('Use a short motion query for component-discovery; read exact IDs via scene-templates.');
|
|
138
|
+
const [templates, hyperframes] = await Promise.all([this.catalog('scene-templates'), this.catalog('hyperframes-components')]);
|
|
139
|
+
const ports = new Map(hyperframes.filter(entry => entry.nativeStatus === 'ported').map(entry => [entry.nativeTemplateId, entry]));
|
|
140
|
+
const phrase = terms.join(' ');
|
|
141
|
+
const matches = templates.flatMap(template => {
|
|
142
|
+
const port = ports.get(template.id);
|
|
143
|
+
const name = searchWords(`${template.id} ${template.label}`);
|
|
144
|
+
const tags = new Set(searchWords((port?.tags ?? []).join(' ')));
|
|
145
|
+
const details = new Set(searchWords(`${template.description ?? ''} ${(template.whenToUse ?? []).join(' ')}`));
|
|
146
|
+
const rank = terms.map(term => name.includes(term) ? 6 : tags.has(term) ? 3 : details.has(term) ? 1 : 0);
|
|
147
|
+
if (rank.includes(0)) return [];
|
|
148
|
+
const score = rank.reduce((total, value) => total + value, 0)
|
|
149
|
+
+ (name.join(' ').includes(phrase) ? 6 : 0)
|
|
150
|
+
+ (searchWords(template.id).join(' ') === phrase ? 10 : 0);
|
|
151
|
+
return [{ score, candidate: {
|
|
152
|
+
id: template.id, label: template.label, description: template.description,
|
|
153
|
+
visualMode: template.visualMode, requiredImages: template.requiredImages ?? [], requiredVideos: template.requiredVideos ?? [],
|
|
154
|
+
source: { topic: 'scene-templates', id: template.id },
|
|
155
|
+
} }];
|
|
156
|
+
}).sort((a, b) => b.score - a.score || a.candidate.id.localeCompare(b.candidate.id, 'en'));
|
|
157
|
+
const start = Math.min(input.offset ?? 0, matches.length);
|
|
158
|
+
const end = Math.min(start + (input.limit ?? 2), matches.length);
|
|
159
|
+
return { topic: input.topic, origin: 'installed-client-library', libraryVersion: (await this.manifest()).version,
|
|
160
|
+
entries: matches.slice(start, end).map(match => match.candidate), total: matches.length,
|
|
161
|
+
...(end < matches.length ? { nextOffset: end } : {}),
|
|
162
|
+
next: matches.length ? 'Read the exact source of the chosen candidate. Adapt only if it serves the brief.' : 'Try another short motion term once; if nothing fits, author native Svelte without forcing an unrelated template.',
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
|
|
131
166
|
async reference(input = {}) {
|
|
132
167
|
validateInput(input);
|
|
168
|
+
if (input.topic === 'component-discovery') return this.discoverComponents(input);
|
|
133
169
|
const catalog = await this.catalog(input.topic);
|
|
134
170
|
const query = (input.query ?? '').trim().toLowerCase();
|
|
135
171
|
const matches = catalog.filter(entry => (!input.id || entry.id === input.id)
|