@scenerok/sdk 0.23.0 → 0.25.0
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/package.json
CHANGED
|
@@ -34,7 +34,9 @@ match, and prefer a plugin whenever the user pasted structured source data.
|
|
|
34
34
|
`scenerok_run_plugin` with the pinned ref, inputs and `maxTokens` (required).
|
|
35
35
|
The result includes the next `scenerok_check_render_status` call when a
|
|
36
36
|
render is created, plus the **filled VidScript** (`vidscript`) and an `edit`
|
|
37
|
-
hint for changing it.
|
|
37
|
+
hint for changing it. The tool sends an `idempotencyKey` (one per paid call,
|
|
38
|
+
echoed back) so a retried call replays the original run and render instead of
|
|
39
|
+
rendering and charging again; pass your own only to retry an exact call.
|
|
38
40
|
6. **Poll** — `scenerok_check_render_status` with the `renderId` until the MP4
|
|
39
41
|
is ready.
|
|
40
42
|
7. **Improve a finished run** — `scenerok_get_plugin_run` with the `runId` when
|
|
@@ -42,7 +44,32 @@ match, and prefer a plugin whenever the user pasted structured source data.
|
|
|
42
44
|
`scenerok_render_video` the edited copy. See
|
|
43
45
|
[Editing a generated video](#editing-a-generated-video).
|
|
44
46
|
|
|
45
|
-
The tool list is stable:
|
|
47
|
+
The tool list is stable: seven plugin tools, not one tool per plugin.
|
|
48
|
+
|
|
49
|
+
## UI actions (headless)
|
|
50
|
+
|
|
51
|
+
A plugin with a UI can expose non-interactive actions. Use
|
|
52
|
+
`scenerok_ui_action` with `{ ref, component, props?, inputs?, action, payload? }`
|
|
53
|
+
when the plugin's `component.json#agent.actions` lists what you need (the
|
|
54
|
+
component listing on the plugin page shows it). It runs the same controller the
|
|
55
|
+
UI runs, with no browser, and returns:
|
|
56
|
+
|
|
57
|
+
```jsonc
|
|
58
|
+
{
|
|
59
|
+
"inputs": { "trimStartMs": 2000 }, // a proposed tier-1 patch
|
|
60
|
+
"document": { "api": "scenerok.ui.document/1", "root": {} },
|
|
61
|
+
"events": [{ "name": "trim", "payload": { "startMs": 2000 } }]
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Feed the patch into `scenerok_run_plugin`. Nothing is applied or charged by the
|
|
66
|
+
action itself.
|
|
67
|
+
|
|
68
|
+
An interactive action (recording a take, opening a picker) returns an **error**
|
|
69
|
+
with `code: "ui_required"` and `{ component, action, fallbackInput, hint }`. Do
|
|
70
|
+
not retry it: pass an existing value for `fallbackInput` (usually a
|
|
71
|
+
`scenerok://asset/<id>` from the user's workspace) to the normal plugin inputs,
|
|
72
|
+
or ask the user to open the run page. Actions never spend tokens.
|
|
46
73
|
|
|
47
74
|
## CLI equivalents
|
|
48
75
|
|
|
@@ -61,8 +88,10 @@ scenerok plugin render-draft <draft-id> --vidscript draft.vid
|
|
|
61
88
|
|
|
62
89
|
`--set key=value` (repeatable, dotted paths) overrides or adds single inputs
|
|
63
90
|
without a JSON file. `--max-tokens` is required; `--json` prints the raw
|
|
64
|
-
contract. `scenerok plugin draft
|
|
65
|
-
|
|
91
|
+
contract (including the generated retry key). `scenerok plugin draft`,
|
|
92
|
+
`plugin run` and `plugin render-draft` all take `--idempotency-key`: one key per
|
|
93
|
+
action, reused on a retry, so a retried request replays the original result
|
|
94
|
+
instead of charging again.
|
|
66
95
|
|
|
67
96
|
## Draft, preview, render
|
|
68
97
|
|
|
@@ -86,7 +115,9 @@ estimate → draft (providers + plugin fee) → preview + edit → render (rende
|
|
|
86
115
|
2. Show the user the preview/script. If they want changes, rewrite the
|
|
87
116
|
VidScript and pass it as `scenerok_render_draft`'s `vidscript`.
|
|
88
117
|
3. `scenerok_render_draft` — `{ draftId }` or `{ draftId, vidscript }`. Returns
|
|
89
|
-
the render and a `scenerok_check_render_status` call.
|
|
118
|
+
the render and a `scenerok_check_render_status` call. It sends its own
|
|
119
|
+
`idempotencyKey` per call (echoed back) so a retried render replays the
|
|
120
|
+
original one; pass the same key to retry an exact render.
|
|
90
121
|
|
|
91
122
|
**Billing, in one line each**
|
|
92
123
|
|
|
@@ -104,7 +135,11 @@ estimate → draft (providers + plugin fee) → preview + edit → render (rende
|
|
|
104
135
|
not re-run the plugin. Do not use a new key here: that would pay for a second
|
|
105
136
|
draft.
|
|
106
137
|
- Rendering a draft charges **render seconds only** — never the fee again — and
|
|
107
|
-
rendering the same draft twice is two renders with one fee
|
|
138
|
+
rendering the same draft twice is two renders with one fee (a retry with the
|
|
139
|
+
same `idempotencyKey` is one render).
|
|
140
|
+
- A retried **run** or **draft render** with the same `idempotencyKey` replays
|
|
141
|
+
the original result (`duplicate: true`): nothing renders and nothing is
|
|
142
|
+
charged. Changed inputs or an edited script is a new action — use a new key.
|
|
108
143
|
- A redraft with different inputs is a **new paid draft**. Reuse the
|
|
109
144
|
`idempotencyKey` only to retry the same request (it is then free).
|
|
110
145
|
- An edited draft script may only use the plugin's own pinned blocks/kit, assets
|