MUTATION_TESTING
AgentThe agent package's pure, deterministic core (the chat permission gate, the control-tool plumbing, JSON extraction, and the…
**Navigation**: [Agents package rules](../AGENTS.md) → **Headless tool surfaces**
Claude Code
$ npx -y skills add nodetool-ai/nodetool --agent claude-code
Cursor
Cursor also loads subagents from .claude/agents, so copy this file there to use it in Cursor.
**Navigation**: [Agents package rules](../AGENTS.md) → **Headless tool surfaces**
Paths are relative to `packages/agents/` unless they name another package.
The headless path from a written script to voiced takes and an assembled voiceover sequence. The editor voices a line over the chat WebSocket's `generate_media` / `transcribe_audio` RPCs, and the `nodetool.script.*` nodes do it inside a workflow; an agent outside the browser had neither. These call the provider directly, save each take as an asset, and write it back onto the persisted script.
| Tool | Does | |---|---| | `list_scripts` | Scripts newest first, with line and voiced counts | | `get_script` | Cast, lines, and each line's voicing status | | `voice_script_lines` | TTS per line → a take, current on its line | | `assemble_script_timeline` | Voiced takes → a saved `timeline_sequences` row |
`get_script` reports the status the editor's gutter shows — `draft` (never voiced), `stale` (text or voice changed since the take), `voiced`, `no_voice` — and `voice_script_lines` defaults to every line that is draft or stale, so a whole script is one call. Each line uses its own voice (its override, else its speaker's) unless the call passes provider+model+voice to override them all; a half-specified override is an error, not a guess. Lines are voiced concurrently (default 3, max 8, 60 per call) and each take lands through a CAS on the row's `updated_at`.
Synthesis delegates to `GenerateSpeechTool`, so the encoded/streaming-PCM provider split is handled in one place. Word timings come from a best-effort ASR pass (`whisper-1` by default, `transcribe: false` to skip it) and ride into the assembled clips as captions. Take duration is the container's own, probed in process through `@nodetool-ai/runtime/media`, falling back to the last word timing and then to the 3s placeholder. A take stays assemblable without an exact length.
The voice rule (`effectiveVoice`), the staleness rule (`needsVoicing`) and the script → timeline mapping (`buildScriptTimeline`) live in `@nodetool-ai/timeline`; the editor's "Send to timeline" and `nodetool.script.ScriptToTimeline` call the same functions, so the three surfaces cannot drift. Re-assembly rewrites this script's voiceover track in place and keeps clips other surfaces added.
Tests: `tests/script-voice-tools.test.ts` (in-memory DB, fake provider — no network).
The headless path from a directed storyboard to rendered media and an assembled cut. The editor has always had this path — the Storyboard surface builds a throwaway `TextToImage → Output` / `ImageToVideo → Output` graph per shot and runs it in the browser — but an agent outside the browser had to author, save, and run a workflow per shot, or drive the `ui_storyboard_*` tools, which only work while that board is open. These call the provider directly, save each result as an asset, and write it back onto the persisted board.
| Tool | Does | |---|---| | `list_storyboards` | Boards newest first, with per-board still/clip counts | | `create_storyboard` | Blank board (then `edit_storyboard` adds shots) | | `get_storyboard` | Shots with ids, status, and whether each has a still/clip | | `direct_storyboard` | Runs the Director over the board's brief/genre/style and writes the screenplay; `redirect` keeps retained shots' ids and media | | `render_storyboard_stills` | `text_to_image` per shot → the shot's keyframe | | `render_storyboard_clips` | the shot's clip: `image_to_video` seeded by the keyframe, or `text_to_video` from the prompt | | `revise_storyboard_clip` | `video_to_video` revision of one shot's clip | | `assemble_storyboard_timeline` | Rendered clips → a saved `timeline_sequences` row | | `derive_shot_from_clip` | Frames of a shot clip → a new reference-to-video shot after its source, and a draft clip following it on a new track above the source clip | | `get_storyboard_one_take` | The creator's one-take prompt, the block compiled from the board, the full prompt, `[Image N]` references and warnings | | `update_storyboard_one_take` | Sets the creator's one-take prompt and shots' `end_state` / `sound` |
`edit_storyboard` is the document half: beside the shot ops it carries the guided flow's `set_setup`, the scene ops (`move_shot`, `duplicate_shot`, `update_scene`, `create_scene`, `merge_scene`), `set_style`, and the version ops (`select_version`, `delete_version`, `add_keyframe_version`). Every one mirrors a `ui_storyboard_*` browser tool and writes the same document shape, so a board edited headlessly and one edited in the editor cannot diverge (PRD § 7.10).
Both render tools take `targets` (shot ids, indexes, or slugs) and default to "whatever still needs this step", so a whole board is one call. `stale_only` narrows that to the shots whose selected version was rendered from inputs the shot no longer has (`isVersionStale`), which is how a style change is re-rendered without re-rendering the board. Shots render concurrently (default 3, max 8, 24 shots per call). Every write is a CAS on the row's `updated_at` with a bounded retry, because concurrent renders all land on the same board document; a conflicting write re-reads and re-applies rather than clobbering.
The provider and model come from the call, else from the board's own `imageModel` / `videoModel`. There is no fallback default — an unset model is an error naming `find_model`, not silent spend on a model nobody chose.
`Shot.render_mode` decides whether a clip needs a still. `"keyframe"` (the default) animates the selected still; `"direct"` renders from the prompt and skips the stills step entirely, for shots where first-frame conditioning is the wrong trade — heavy motion, which I2V renders stiffer than the same model's T2V, and native-audio models, which are weakest on their image path. A direct shot's prompt carries framing and board st
Open-source AI film studio · agent + node workflows Direct AI films, shot by shot. Start with one sentence. The agent writes the story, draws a still for every shot, and cuts the clips on a timeline.
The agent package's pure, deterministic core (the chat permission gate, the control-tool plumbing, JSON extraction, and the…
**Navigation**: [Agents package rules](../AGENTS.md) → **Capabilities and tool sources**
**Navigation**: [Agents package rules](../AGENTS.md) → **Running Agents from CLI**
**Navigation**: [Agents package rules](../AGENTS.md) → **CodeAct Execution**
**Navigation**: [Agents package rules](../AGENTS.md) → **Eval suites**
**Navigation**: [Agents package rules](../AGENTS.md) → **Graph authoring**
Agent for managing AI prompts on prompts.chat - search, save, improve, and organize your prompt library.
정밀(strict) 모드 1단계 진단 에이전트. 글 전체를 한 번에 보고 "가장 지배적인 AI 티 패턴 3~6개"를 taxonomy ID와 함께 진단한다. 불안정한 span 열거(0↔18개로 요동) 대신 "무엇이 이 글을…
Topic Clusters curator for the Claude Blog Brain. Maintains and answers from the Topic Clusters theme of the brain, grounded in…
Optional gallery research helper. Use when a caller wants to find references, explore styles, build a mood board, or needs…