rushes 0.11.0 → 0.12.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.
@@ -161,9 +161,11 @@ export const SectionSchema = z
161
161
  takes: z.array(TakeSchema).default([]),
162
162
  })
163
163
  .refine((s) => s.end > s.start, { message: "end must be after start", path: ["end"] });
164
- export const ScriptSchema = fileObject({
165
- schema: z.literal(1),
166
- rev: z.number().int().nonnegative(),
164
+ /**
165
+ * §31.3: one film's script: its reading speed, its sections and the highest s<n> number it ever gave. A schema 1
166
+ * script.json is this, with `schema` and `rev`; a schema 2 one keeps one of these per film.
167
+ */
168
+ export const FilmScriptSchema = fileObject({
167
169
  wordsPerSecond: z.number().positive().default(2.6),
168
170
  sections: z.array(SectionSchema).default([]),
169
171
  // The highest s<n> number ever given to a section, so a removed section's id is never handed out
@@ -171,6 +173,25 @@ export const ScriptSchema = fileObject({
171
173
  // the ids it can see.
172
174
  sectionCounter: z.number().int().nonnegative().optional(),
173
175
  });
176
+ /** script.json as written before §31: one script for the project. Still how a project with no film yet keeps it. */
177
+ export const ScriptV1Schema = fileObject({
178
+ schema: z.literal(1),
179
+ rev: z.number().int().nonnegative(),
180
+ wordsPerSecond: z.number().positive().default(2.6),
181
+ sections: z.array(SectionSchema).default([]),
182
+ sectionCounter: z.number().int().nonnegative().optional(),
183
+ });
184
+ /** §31.3: script.json schema 2, one script per film, keyed by video id. */
185
+ export const ScriptV2Schema = fileObject({
186
+ schema: z.literal(2),
187
+ rev: z.number().int().nonnegative(),
188
+ films: z.record(id, FilmScriptSchema).default({}),
189
+ });
190
+ /**
191
+ * script.json. A schema 1 file is the first film's script (or, with no film yet, the project's); it is written back
192
+ * as schema 2 by the first change made once there is a film (core/script.ts: filmScriptDraft).
193
+ */
194
+ export const ScriptSchema = z.discriminatedUnion("schema", [ScriptV1Schema, ScriptV2Schema]);
174
195
  export const BoxSchema = fileObject({
175
196
  x: z.number().min(0).max(1),
176
197
  y: z.number().min(0).max(1),
@@ -342,20 +363,20 @@ export function variantFilms(v) {
342
363
  return v.videos ?? (v.video === undefined ? [] : [v.video]);
343
364
  }
344
365
  /**
345
- * Whether a read, bed or pass is on a film. One on no film is on it only in a project with one film
346
- * (there is nowhere else for it to be); with several, it is on none until it is put on one.
366
+ * §31.2.4: whether a read, bed or pass is on a film. One on no film is on the project's first film (`videos[0]`):
367
+ * nothing is on no film, and the one-time move (§31.4) writes that down.
347
368
  */
348
- export function onFilm(v, videoId, filmCount) {
369
+ export function onFilm(v, videoId, videos) {
349
370
  const films = variantFilms(v);
350
- return films.length === 0 ? filmCount <= 1 : films.includes(videoId);
371
+ return films.length === 0 ? videos.length === 0 || videos[0].id === videoId : films.includes(videoId);
351
372
  }
352
373
  /** The lanes one film hears: each keeps only the variants on that film (see onFilm), and a lane
353
374
  * left with none is dropped. With no film named, every lane as it is. */
354
- export function lanesForVideo(lanes, videoId, filmCount) {
375
+ export function lanesForVideo(lanes, videoId, videos) {
355
376
  if (!videoId)
356
377
  return lanes;
357
378
  return lanes
358
- .map((l) => ({ ...l, variants: l.variants.filter((v) => onFilm(v, videoId, filmCount)) }))
379
+ .map((l) => ({ ...l, variants: l.variants.filter((v) => onFilm(v, videoId, videos)) }))
359
380
  .filter((l) => l.variants.length > 0);
360
381
  }
361
382
  export const BatchSchema = fileObject({
@@ -366,6 +387,12 @@ export const BatchSchema = fileObject({
366
387
  sectionIds: z.array(z.string()).default([]),
367
388
  sentAt: z.string(),
368
389
  prompt: z.string(),
390
+ // §31.2.2: the film whose notes Send sent. Absent on a batch from before, and on one sent with no film yet.
391
+ video: z.string().nullable().optional(),
392
+ // I3: the hand-over was refused while Send to AI was on and nothing started (not signed in, not installed), so the
393
+ // notes still wait in this batch for Send again. Kept in the file, not the server's memory, so a restart can't strand
394
+ // them. Cleared when the batch is handed over again.
395
+ undelivered: z.object({ at: z.string(), why: z.string() }).nullable().optional(),
369
396
  });
370
397
  export const BatchesFileSchema = fileObject({
371
398
  schema: z.literal(1),
@@ -482,6 +509,9 @@ export const BriefStateSchema = fileObject({
482
509
  rev: z.number().int().nonnegative(),
483
510
  baseline: z.string().max(1_000_000).default(""),
484
511
  seen: z.string().max(64).default(""),
512
+ // §31.3: every other film's own baseline and hash, keyed by video id. The first film's are the top-level two, so a
513
+ // project with one film keeps the same file.
514
+ films: z.record(id, fileObject({ baseline: z.string().max(1_000_000).default(""), seen: z.string().max(64).default("") })).optional(),
485
515
  });
486
516
  // §25.3: a visual is one post: a still, or a carousel of pages. A version holds every page it shows, the ones it
487
517
  // inherited from the version before included, so nothing downstream has to work inheritance out.
@@ -519,8 +549,15 @@ export const VisualsFileSchema = fileObject({
519
549
  // session to resume. What the agent may do unasked (AgentRules) is kept outside the project (R10), where the agent
520
550
  // can't change it.
521
551
  export const AGENTS = ["claude", "codex"];
522
- /** What the agent may do without asking: edit files in the project (the default), or ask for everything. */
523
- export const AgentPermissionsSchema = z.enum(["project-edits", "ask-all"]);
552
+ /**
553
+ * What the agent may do without asking (§33), one menu row each. The first two ids are kept from before §33, so older
554
+ * rules files still read: "ask-all" is Manual (every action asks Rushes) and "project-edits" is Accept edits (the
555
+ * default: edits in the project go through, commands ask, Always rules apply). "auto" hands each decision to the
556
+ * agent's own safety reviewer and "bypass" checks nothing. Only the user picks those two, from the menu or the first-Send
557
+ * sheet; nothing in a project can set them (R10).
558
+ */
559
+ export const AGENT_PERMISSIONS = ["ask-all", "project-edits", "auto", "bypass"];
560
+ export const AgentPermissionsSchema = z.enum(AGENT_PERMISSIONS);
524
561
  export const AlwaysRuleSchema = z.object({ kind: z.string().max(32), command: z.string().max(200).nullable() });
525
562
  /** At most this many Always rules are kept; a longer list read from disk keeps its newest ones. */
526
563
  export const ALWAYS_KEPT = 50;
@@ -560,6 +597,15 @@ export const AgentRulesReadSchema = z.object({
560
597
  setUp: z.boolean().default(false),
561
598
  agent: z.enum(AGENTS).nullable().default(null),
562
599
  });
600
+ /**
601
+ * §32: Send to AI's Mac-wide default, kept beside the per-project rules (server/agent/rules.ts), outside every project:
602
+ * the agent the user last chose (null after Copy a prompt) and what it may do. A project with no rules file yet starts
603
+ * from it, so Send to AI is set up once per Mac, not once per project. Always rules stay per project.
604
+ */
605
+ export const AgentDefaultsSchema = z.object({
606
+ agent: z.enum(AGENTS).nullable().default(null),
607
+ permissions: AgentPermissionsSchema.default("project-edits"),
608
+ });
563
609
  export const FILES = {
564
610
  project: { name: "project.json", schema: ProjectSchema },
565
611
  script: { name: "script.json", schema: ScriptSchema },
@@ -129,3 +129,70 @@ export function addTake(script, sectionId, input) {
129
129
  s.takes.push(take);
130
130
  return take;
131
131
  }
132
+ // ---- §31.3: one script per film ----
133
+ const WPS = 2.6;
134
+ /** A film with no script yet: nothing in it, at the usual reading speed. */
135
+ export const emptyScript = () => ({ wordsPerSecond: WPS, sections: [] });
136
+ /**
137
+ * The film whose script a schema 1 file is: the project's first film, or none while there is no film (§31.3: a
138
+ * project with no film yet keeps its plan files as they are, and they become the first film's when it is made).
139
+ */
140
+ const firstFilmId = (project) => project.videos[0]?.id ?? null;
141
+ /**
142
+ * One film's script, read from script.json. With no film named (a project with no film yet, or a caller that doesn't
143
+ * know one) it is the first film's. A schema 1 file is the first film's script; any other film has none until one is
144
+ * set. What comes back is the file's own object where there is one, so a caller inside a store update may change it;
145
+ * use filmScriptDraft to change a film's script, since it also makes the room.
146
+ */
147
+ export function filmScript(file, project, video) {
148
+ const first = firstFilmId(project);
149
+ const film = video ?? first;
150
+ if (file.schema === 1)
151
+ return film === null || film === first ? file : emptyScript();
152
+ if (film === null)
153
+ return emptyScript();
154
+ return file.films[film] ?? emptyScript();
155
+ }
156
+ /**
157
+ * The script to change for a film, inside a store update of script.json. A schema 1 file becomes schema 2 here, its
158
+ * script kept as the first film's, once the project has a second film to tell it from (§31.3). With no film yet, or
159
+ * one film, it is changed as it is, so a one-film project keeps the very file it had (§31.7). A film with no script
160
+ * gets an empty one.
161
+ */
162
+ export function filmScriptDraft(file, project, video) {
163
+ const first = firstFilmId(project);
164
+ const film = video ?? first;
165
+ if (file.schema === 1) {
166
+ if (first === null || (film === first && project.videos.length < 2))
167
+ return file;
168
+ toSchema2(file, first);
169
+ }
170
+ const v2 = file;
171
+ if (film === null)
172
+ throw new InvalidError("Name the film this script is for");
173
+ return (v2.films[film] ??= emptyScript());
174
+ }
175
+ /** Rewrites a schema 1 draft in place as schema 2, its script the first film's. */
176
+ export function toSchema2(file, first) {
177
+ if (file.schema !== 1)
178
+ return;
179
+ const { wordsPerSecond, sections, sectionCounter } = file;
180
+ const loose = file;
181
+ delete loose.wordsPerSecond;
182
+ delete loose.sections;
183
+ delete loose.sectionCounter;
184
+ loose.schema = 2;
185
+ loose.films = { [first]: { wordsPerSecond, sections, ...(sectionCounter === undefined ? {} : { sectionCounter }) } };
186
+ }
187
+ /** Every film's scripts, for what has to know every take whichever film it belongs to (media, the Assets list, the log). */
188
+ export function scriptsOf(file) {
189
+ return file.schema === 1 ? [{ video: null, script: file }] : Object.entries(file.films).map(([video, script]) => ({ video, script }));
190
+ }
191
+ /** The sections of one film's script, or of every film's when given the whole file. */
192
+ export function sectionsOf(script) {
193
+ return "sections" in script ? script.sections : allSections(script);
194
+ }
195
+ /** Every film's sections in one list (ids may repeat across films: each film numbers its own). */
196
+ export function allSections(file) {
197
+ return scriptsOf(file).flatMap((s) => s.script.sections);
198
+ }
package/dist/core/tabs.js CHANGED
@@ -1,15 +1,23 @@
1
- import { STAGES } from "./schema.js";
1
+ import { STAGES, lanesForVideo } from "./schema.js";
2
+ import { noteOnFilm } from "./films.js";
2
3
  import { noteInPlay } from "./project.js";
3
4
  import { noteState } from "./noteState.js";
4
5
  import { isChanged } from "./script.js";
5
6
  function laneHasVariants(p, stage) {
6
7
  return p.lanes.some((l) => l.stage === stage && l.variants.length > 0);
7
8
  }
8
- export function tabStates(p, s, n, v = { visuals: [] }) {
9
- const picture = p.videos.some((v) => v.versions.length > 0);
10
- const voice = laneHasVariants(p, "voice");
11
- const music = laneHasVariants(p, "music");
12
- const sfx = laneHasVariants(p, "sfx");
9
+ /**
10
+ * Each tab: unlocked or not, and its open items. §31.5: with a film, that film's (its cuts, the takes on it, its
11
+ * script, its notes and the shared visuals' notes); with none, the whole project's (a project with no film yet). `s`
12
+ * is the script that goes with it: that film's.
13
+ */
14
+ export function tabStates(p, s, n, v = { visuals: [] }, film) {
15
+ const own = film ? p.videos.find((x) => x.id === film) : undefined;
16
+ const picture = own ? own.versions.length > 0 : p.videos.some((v) => v.versions.length > 0);
17
+ const heard = { lanes: lanesForVideo(p.lanes, own?.id, p.videos) };
18
+ const voice = laneHasVariants(heard, "voice");
19
+ const music = laneHasVariants(heard, "music");
20
+ const sfx = laneHasVariants(heard, "sfx");
13
21
  const unlocked = {
14
22
  script: s.sections.length > 0,
15
23
  picture,
@@ -22,7 +30,7 @@ export function tabStates(p, s, n, v = { visuals: [] }) {
22
30
  };
23
31
  return STAGES.map((stage) => {
24
32
  // §26: a shelved film's open notes are kept but do not count.
25
- const open = n.notes.filter((x) => x.stage === stage && x.status === "todo" && noteInPlay(x, p));
33
+ const open = n.notes.filter((x) => x.stage === stage && x.status === "todo" && noteInPlay(x, p) && noteOnFilm(x, own?.id, p.videos));
26
34
  const rows = stage === "script" ? s.sections.filter((x) => isChanged(x) || x.status === "flagged").length : 0;
27
35
  return { stage, unlocked: unlocked[stage], todo: open.length + rows, sent: open.filter((x) => noteState(x) === "sent").length };
28
36
  });
@@ -48,7 +48,7 @@ export function takeState(variant, lane, use) {
48
48
  const SOUNDS = ["voice", "music", "sfx"];
49
49
  /** Every take one film hears (no film: the whole project), per sound, newest round first, with its state. */
50
50
  export function filmTakes(project, picks, videoId) {
51
- const lanes = lanesForVideo(project.lanes, videoId, project.videos.length);
51
+ const lanes = lanesForVideo(project.lanes, videoId, project.videos);
52
52
  const use = inUse({ lanes }, picksForVideo(picks, videoId));
53
53
  const video = videoId ? project.videos.find((v) => v.id === videoId) : undefined;
54
54
  const out = { voice: [], music: [], sfx: [] };
package/dist/mcp/tools.js CHANGED
@@ -9,7 +9,7 @@ import { NOTE_STATES } from "../core/noteState.js";
9
9
  const project = z.string().optional().describe("Project folder. Defaults to the current working directory.");
10
10
  const stage = z.enum(["script", "picture", "voice", "music", "sfx", "mix", "visuals"]);
11
11
  const fileKind = z.enum(["doc", "image", "caption", "export", "delivery", "edit"]);
12
- const assetKind = z.enum(["screenshot", "cut", "proxy", "take", "music", "sfx", "voice", "doc", "image", "caption", "export", "delivery", "edit"]);
12
+ const assetKind = z.enum(["screenshot", "cut", "proxy", "take", "music", "sfx", "voice", "visual", "doc", "image", "caption", "export", "delivery", "edit"]);
13
13
  // §20.7: a file to bring in. The server checks everything else (inside the project, the kind, the limits).
14
14
  const film = z.string().min(1).max(200);
15
15
  const bringInItem = z.object({
@@ -47,6 +47,31 @@ function fail(e) {
47
47
  const message = e instanceof ApiError ? (e.body.error === "not_json" ? e.message : `${e.message} (${e.body.error ?? e.status})${issuesOf(e.body)}`) : e.message;
48
48
  return { content: [{ type: "text", text: message }], isError: true };
49
49
  }
50
+ // §31.6: a film's material (its script, notes, Activity, files, tabs) is asked for by film: its id or its name.
51
+ const filmArg = z
52
+ .string()
53
+ .min(1)
54
+ .max(200)
55
+ .optional()
56
+ .describe("The film (its id or name). With one film it may be left out; with several it is required (the error lists them). A batch names its film: use that.");
57
+ /**
58
+ * §31.6: the film to pass on for a tool that reads or writes a film's material. The one named; with one film (or none)
59
+ * nothing, so the call is the same as ever; with several and none named, an error that lists them.
60
+ */
61
+ async function filmFor(c, film, what) {
62
+ if (film)
63
+ return film;
64
+ let films = [];
65
+ try {
66
+ films = ((await c.get("/api/tabs")).films ?? []);
67
+ }
68
+ catch {
69
+ return undefined;
70
+ }
71
+ if (films.length < 2)
72
+ return undefined;
73
+ throw new Error(`This project has ${films.length} films, so pass \`film\` to say which one ${what} is for: ${films.map((f) => (f.name === f.id ? f.id : `${f.name} (${f.id})`)).join(", ")}.`);
74
+ }
50
75
  /** Wrap a handler so API errors come back as tool errors the agent can read. */
51
76
  function safe(fn) {
52
77
  return async (args) => {
@@ -147,9 +172,20 @@ export function createMcpServer(ctx) {
147
172
  }, safe(async ({ project, video, version }) => (await ctx.client(project)).put(`/api/videos/${encodeURIComponent(video)}/lock`, { version })));
148
173
  server.registerTool("rushes_status", {
149
174
  title: "Rushes status",
150
- description: "Which tabs are unlocked and how many open items each has (`todo`), and how many of those notes the user has already sent you (`sent`). Also `brief`: whether brief.md exists, its status (draft or approved, set when the user presses Approve) and how many sections the user changed; `storyboard`: whether storyboard.md exists, how many shots there are, how many are approved and how many the user changed; and `build`: whether planning has begun (`started`), whether the brief, every script section (when there is a script) and every shot are approved (`ready`), and what it is `waitingOn`. Also `films`: every film with `shelved` (the time the user shelved it, or null). A shelved film is one the user has set aside: leave it alone, make no new cuts of it and fix none of its notes unless the user says to. Its open notes are not counted in the tabs.",
151
- inputSchema: { project },
152
- }, safe(async ({ project }) => (await ctx.client(project)).get("/api/tabs")));
175
+ description: "Which tabs are unlocked and how many open items each has (`todo`), and how many of those notes the user has already sent you (`sent`). Also `brief`: whether brief.md exists (the film's own: see `plans`), its status (draft or approved, set when the user presses Approve) and how many sections the user changed; `storyboard`: whether storyboard.md exists (the film's own), how many shots there are, how many are approved and how many the user changed; and `build`: whether planning has begun (`started`), whether the brief, every script section (when there is a script) and every shot are approved (`ready`), and what it is `waitingOn`. Also `films`: every film with `shelved` (the time the user shelved it, or null), and `plans`: where each film's own brief and storyboard are, by film id (the first film's are brief.md and storyboard.md at the project root, every other film's are films/<film-id>/brief.md and films/<film-id>/storyboard.md). A shelved film is one the user has set aside: leave it alone, make no new cuts of it and fix none of its notes unless the user says to. Its open notes are not counted in the tabs. Everything but `films` and `plans` is one film's: pass `film`. With several films and no `film`, you get the whole project's tabs, `films` and `plans` only.",
176
+ inputSchema: { project, film: filmArg },
177
+ }, safe(async ({ project, film }) => {
178
+ const c = await ctx.client(project);
179
+ if (film)
180
+ return c.get(`/api/tabs?video=${encodeURIComponent(film)}`);
181
+ const r = await c.get("/api/tabs");
182
+ // §31.6: the brief, storyboard and build are a film's. With several films and none named, they are left out.
183
+ if (Array.isArray(r?.films) && r.films.length > 1) {
184
+ const { brief: _b, storyboard: _s, build: _p, ...rest } = r;
185
+ return { ...rest, note: `This project has ${r.films.length} films. Pass \`film\` for one film's tabs, brief, storyboard and build.` };
186
+ }
187
+ return r;
188
+ }));
153
189
  server.registerTool("rushes_add_version", {
154
190
  title: "Add a cut",
155
191
  description: "Register a new cut of a video. The first cut creates the video. Returns the new version id (v1, v2 ...). When the cut is likely to play badly in a browser (4K, over 1.5 GB, or a codec such as ProRes), it also returns proxySuggested: true and proxyReason; Picture offers the user a proxy. If the project has autoProxy on, proxyJob is the proxy already being made. Give every cut a short `label` (" + LABEL_MAX + " characters at most) saying what changed, e.g. \"launch 1.45x slower\", and put the detail in `note`: the version list shows the label. Pass `formats` to register the other shapes of the same cut in one call; the reply then carries `formatWarnings` (a list, one entry for each shape more than 0.1 s off the cut's length; `warning` here means Picture is locked). When the plan (brief, script, storyboard) has been started but is not all approved, it carries `planWarning` saying what is outstanding: a nudge, never a refusal. A film's first cut also starts with the storyboard's shots. A cut of a shelved film brings it back (the reply has `restored: true`), so make one only when the user wants that film worked on again.",
@@ -251,7 +287,7 @@ export function createMcpServer(ctx) {
251
287
  video: z
252
288
  .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
253
289
  .optional()
254
- .describe("The film (id or name) this read, bed or pass is for, or a list of films when one bed is fitted to several: only those films' Voiceover, Music, Sound effects and Mix list it. Rushes works out one film when the name or file name starts with the film's first word (\"f3a SFX pass 3\" for \"f3a One phone\"), but always give it in a project with more than one film: one on no film is listed on none of their tabs (it waits, folded, under \"Not on this film\"), and the reply carries a `warning`. To move one later, use rushes_set_films."),
290
+ .describe("The film (id or name) this read, bed or pass is for, or a list of films when one bed is fitted to several: only those films' Voiceover, Music, Sound effects and Mix list it. Rushes works out one film when the name or file name starts with the film's first word (\"f3a SFX pass 3\" for \"f3a One phone\"), but always give it in a project with more than one film: one that names no film, and whose film can't be told from its names, goes on the project's first film, and the reply carries a `warning`. To move one later, use rushes_set_films."),
255
291
  cues: z
256
292
  .array(z.object({
257
293
  name: z.string(),
@@ -279,29 +315,43 @@ export function createMcpServer(ctx) {
279
315
  }, safe(async ({ project, lane, variant, videos }) => (await ctx.client(project)).put(`/api/variants/${encodeURIComponent(lane)}/${encodeURIComponent(variant)}/films`, { videos })));
280
316
  server.registerTool("rushes_set_script", {
281
317
  title: "Set the VO script",
282
- description: "Add or update VO script sections. By default this merges by id: send only the sections you changed, with their ids, and new sections without one. Sections you leave out stay as they are. A section that keeps its id keeps the user's edits, direction and takes. Returns the full list.",
318
+ description: "Add or update a film's VO script sections. Each film has its own script: pass `film` (required when the project has several films). By default this merges by id: send only the sections you changed, with their ids, and new sections without one. Sections you leave out stay as they are. A section that keeps its id keeps the user's edits, direction and takes. Returns the full list.",
283
319
  inputSchema: {
284
320
  project,
321
+ film: filmArg,
285
322
  sections: z.array(z.object({ id: z.string().min(1).optional(), start: z.number().nonnegative(), end: z.number().nonnegative(), current: z.string() })),
286
323
  wordsPerSecond: z.number().positive().optional(),
287
324
  replace: z.boolean().optional().describe("replace the whole script; default merges by id"),
288
325
  },
289
- }, safe(async ({ project, ...b }) => (await ctx.client(project)).put("/api/script", b)));
326
+ }, safe(async ({ project, film, ...b }) => {
327
+ const c = await ctx.client(project);
328
+ const video = await filmFor(c, film, "the script");
329
+ return c.put("/api/script", { ...b, ...(video ? { video } : {}) });
330
+ }));
290
331
  server.registerTool("rushes_get_script", {
291
332
  title: "Get the VO script",
292
- description: "The whole script: every section with its current line, the user's proposed line, direction, status and takes, plus wordsPerSecond.",
293
- inputSchema: { project },
294
- }, safe(async ({ project }) => (await ctx.client(project)).get("/api/script")));
333
+ description: "A film's whole script: every section with its current line, the user's proposed line, direction, status and takes, plus wordsPerSecond. Each film has its own: pass `film` (required when the project has several films).",
334
+ inputSchema: { project, film: filmArg },
335
+ }, safe(async ({ project, film }) => {
336
+ const c = await ctx.client(project);
337
+ const video = await filmFor(c, film, "the script");
338
+ return c.get(`/api/script${video ? `?video=${encodeURIComponent(video)}` : ""}`);
339
+ }));
295
340
  server.registerTool("rushes_add_take", {
296
341
  title: "Add a VO take",
297
342
  description: "Compatibility only: attaches a file to a script section as a take, but the Voiceover tab and the mix ignore takes. For voiceover, register each whole read with rushes_add_variant (stage \"voice\", round).",
298
- inputSchema: { project, section: z.string(), file: z.string() },
299
- }, safe(async ({ project, section, file }) => (await ctx.client(project)).post(`/api/script/${encodeURIComponent(section)}/takes`, { file })));
343
+ inputSchema: { project, section: z.string(), file: z.string(), film: filmArg },
344
+ }, safe(async ({ project, section, file, film }) => {
345
+ const c = await ctx.client(project);
346
+ const video = await filmFor(c, film, "the take");
347
+ return c.post(`/api/script/${encodeURIComponent(section)}/takes`, { file, ...(video ? { video } : {}) });
348
+ }));
300
349
  server.registerTool("rushes_list_notes", {
301
350
  title: "List notes",
302
- description: "Notes left in Rushes, filtered by tab, state, status, batch or version. Each note has a `state`: \"todo\" (the user's, not sent yet), \"sent\" (in a batch the user sent: yours to fix) or \"done\". `state: \"sent\"` lists everything you have been given and not finished, whichever batch it came in. A note's `on` says what it's about: null on Picture or for the whole mix, \"<lane>/<variant>\" for a music bed, SFX pass or voice variant, \"<lane>/<variant>:<cue>\" for an SFX cue, \"vo\" for the VO lane on Mix. Older notes may carry a bare variant id, \"vo\" for the assembled read, \"<section>:<take>\" for a take, or a section id. On Picture, a note's `format` is null when it's for every format, or a format id such as \"9x16\" when it's for that shape only. Notes on a shelved film (one the user has set aside) are left out.",
351
+ description: "Notes left in Rushes, filtered by tab, state, status, batch or version. Each note has a `state`: \"todo\" (the user's, not sent yet), \"sent\" (in a batch the user sent: yours to fix) or \"done\". `state: \"sent\"` lists everything you have been given and not finished, whichever batch it came in. A note's `on` says what it's about: null on Picture or for the whole mix, \"<lane>/<variant>\" for a music bed, SFX pass or voice variant, \"<lane>/<variant>:<cue>\" for an SFX cue, \"vo\" for the VO lane on Mix. Older notes may carry a bare variant id, \"vo\" for the assembled read, \"<section>:<take>\" for a take, or a section id. On Picture, a note's `format` is null when it's for every format, or a format id such as \"9x16\" when it's for that shape only. Notes on a shelved film (one the user has set aside) are left out. One film's notes (and the visuals', which are on every film): pass `film`, required when the project has several films unless you name a `batch`.",
303
352
  inputSchema: {
304
353
  project,
354
+ film: filmArg,
305
355
  stage: stage.optional(),
306
356
  state: z.enum(NOTE_STATES).optional().describe('"todo": not sent yet; "sent": sent to you and not done; "done".'),
307
357
  status: z.enum(["todo", "done"]).optional().describe('"todo" is both unsent and sent notes; prefer `state`.'),
@@ -315,11 +365,14 @@ export function createMcpServer(ctx) {
315
365
  .describe('A format id such as "9x16" (or its label, "9:16"): that format\'s Picture notes plus the all-format Picture ones. Picture only: other tabs\' notes are left out.'),
316
366
  onlyThisFormat: z.boolean().optional().describe("With format: only that format's notes, not the all-format ones."),
317
367
  },
318
- }, safe(async ({ project, ...f }) => {
368
+ }, safe(async ({ project, film, ...f }) => {
369
+ const c = await ctx.client(project);
370
+ // A batch is about one film already.
371
+ const video = f.batch === undefined ? await filmFor(c, film, "the notes") : film;
319
372
  // The label "9:16" is the format "9x16".
320
- const asked = { ...f, ...(f.format !== undefined ? { format: f.format.replace(":", "x") } : {}) };
373
+ const asked = { ...f, ...(f.format !== undefined ? { format: f.format.replace(":", "x") } : {}), ...(video ? { video } : {}) };
321
374
  const q = new URLSearchParams(Object.entries(asked).filter(([, v]) => v !== undefined).map(([k, v]) => [k, String(v)]));
322
- const r = await (await ctx.client(project)).get(`/api/notes${q.size ? `?${q}` : ""}`);
375
+ const r = await c.get(`/api/notes${q.size ? `?${q}` : ""}`);
323
376
  // A Rushes from before formats ignores the filter and sends every note, none with a `format`.
324
377
  if (f.format !== undefined && Array.isArray(r?.notes) && r.notes.some((n) => !("format" in n)))
325
378
  return { ...r, note: OLDER_UNFILTERED };
@@ -327,7 +380,7 @@ export function createMcpServer(ctx) {
327
380
  }));
328
381
  server.registerTool("rushes_get_batch", {
329
382
  title: "Get a batch",
330
- description: "The batch the user sent by pressing Send, at the foot of the notes panel (latest by default), with its notes and script sections. It holds every open note from every tab and every film in play: `stage` is the tab when they all came from one, or null when it spans tabs, and each note carries its own `stage` and `video`. A note's `on` says what it's about: null on Picture or for the whole mix, \"<lane>/<variant>\" for a music bed, SFX pass or voice variant, \"<lane>/<variant>:<cue>\" for an SFX cue, \"vo\" for the VO lane on Mix, and on a Script note, the section id of its line (null: the script as a whole). Older notes may carry a bare variant id, \"vo\" for the assembled read, \"<section>:<take>\" for a take, or a section id.",
383
+ description: "The batch the user sent by pressing Send, at the foot of the notes panel (latest by default), with its notes and script sections. A batch is about one film: the film the user was on when they pressed Send, named in `film` (and the batch's `video`); its notes are that film's (plus any on the shared Visuals) and its sections are that film's script's. Pass that film to every tool that asks for one while you work the batch. It holds every open note from every tab on that film: `stage` is the tab when they all came from one, or null when it spans tabs, and each note carries its own `stage` and `video`. A note's `on` says what it's about: null on Picture or for the whole mix, \"<lane>/<variant>\" for a music bed, SFX pass or voice variant, \"<lane>/<variant>:<cue>\" for an SFX cue, \"vo\" for the VO lane on Mix, and on a Script note, the section id of its line (null: the script as a whole). Older notes may carry a bare variant id, \"vo\" for the assembled read, \"<section>:<take>\" for a take, or a section id.",
331
384
  inputSchema: { project, id: z.string().optional() },
332
385
  }, safe(async ({ project, id }) => (await ctx.client(project)).get(`/api/batches/${encodeURIComponent(id ?? "latest")}`)));
333
386
  server.registerTool("rushes_reply", {
@@ -360,9 +413,18 @@ export function createMcpServer(ctx) {
360
413
  }));
361
414
  server.registerTool("rushes_list_assets", {
362
415
  title: "List assets",
363
- description: "Every file in the project: cuts, voice reads, older VO takes, music, SFX and screenshots, with absolute paths. Use it to find a screenshot the user grabbed.",
364
- inputSchema: { project, kind: assetKind.optional() },
365
- }, safe(async ({ project, kind }) => (await ctx.client(project)).get(`/api/assets${kind ? `?kind=${encodeURIComponent(kind)}` : ""}`)));
416
+ description: "A film's files: cuts, voice reads, older VO takes, music, SFX, screenshots, docs and the rest, with absolute paths, plus the project's visuals (`shared: true`: they belong to every film). Use it to find a screenshot the user grabbed. Pass `film` (required when the project has several films).",
417
+ inputSchema: { project, film: filmArg, kind: assetKind.optional() },
418
+ }, safe(async ({ project, film, kind }) => {
419
+ const c = await ctx.client(project);
420
+ const video = await filmFor(c, film, "the files");
421
+ const q = new URLSearchParams();
422
+ if (kind)
423
+ q.set("kind", kind);
424
+ if (video)
425
+ q.set("video", video);
426
+ return c.get(`/api/assets${q.size ? `?${q}` : ""}`);
427
+ }));
366
428
  server.registerTool("rushes_get_picks", {
367
429
  title: "Get picks",
368
430
  description: "Which read, bed and effects pass is in use for a film (`use.voice`, `use.music`, `use.sfx`: one each, or absent when nothing is picked), and each sound's level in dB (where the user wants voice, music and sfx to sit). A take you add is not in use until the user picks it. `lanes` still lists the pick inside each round. `takes` lists every read, bed and effects pass per sound, newest round first, each with its `state`: \"in-use\", \"new\" (arrived since the pick and waiting to be heard), \"earlier\" or \"put-away\" (the user set it aside: don't offer it again), and `madeFor`/`stale` (the cut it was made for, and whether the film has a later one). Picks and levels belong to one film: pass `video` (the film's id, as in the note you are fixing) to read that film's own; without it you get the whole file, each film's under `videos` (with its own `takes`). Section take picks are kept for older projects but not used.",
@@ -370,7 +432,7 @@ export function createMcpServer(ctx) {
370
432
  }, safe(async ({ project, video }) => (await ctx.client(project)).get(`/api/picks${video ? `?video=${encodeURIComponent(video)}` : ""}`)));
371
433
  server.registerTool("rushes_add_file", {
372
434
  title: "Add a file to the library",
373
- description: "Register a project file (a doc, image, caption, export, delivery or edit file) in the Assets library, so it's listed, can be revealed, downloaded and opened. Docs, text and PDFs at the project root, captions at the root, and anything in exports/ are found automatically; other files need this.",
435
+ description: "Register a project file (a doc, image, caption, export, delivery or edit file) in the Assets library, so it's listed, can be revealed, downloaded and opened. Every file is a film's: pass `video` in a project with several films (one that names none is the first film's). Docs, text and PDFs at the project root, captions at the root, and anything in exports/ are found automatically; other files need this.",
374
436
  inputSchema: {
375
437
  project,
376
438
  kind: fileKind,
@@ -403,17 +465,22 @@ export function createMcpServer(ctx) {
403
465
  description: "Call this at the start of a session to catch up: what happened in the project, newest first. Cuts, reads, beds, passes and takes as they were added, the script, picks, notes sent, replies and lines people or agents wrote. Returns `entries` (each with `at`, `area`, `text`, `by`: user, agent or rushes), `earlier` (how many matching lines were left out), `undated` (audio from before the log) and `dropped` (lines removed past 5000).",
404
466
  inputSchema: {
405
467
  project,
468
+ film: filmArg.describe("The film (its id or name): its own lines and the project's, as Activity shows them on that film. Required when the project has several films."),
406
469
  limit: z.number().int().min(1).max(200).default(30).describe("How many lines, newest first. Default 30, at most 200."),
407
470
  area: area.optional().describe("Only this area."),
408
471
  since: z.string().optional().describe("Only lines after this date and time, e.g. 2026-10-07T09:00:00Z."),
409
472
  },
410
- }, safe(async ({ project, limit, area: a, since }) => {
473
+ }, safe(async ({ project, film, limit, area: a, since }) => {
474
+ const c = await ctx.client(project);
475
+ const video = await filmFor(c, film, "the Change Log");
411
476
  const q = new URLSearchParams({ limit: String(limit ?? 30) });
412
477
  if (a)
413
478
  q.set("area", a);
414
479
  if (since)
415
480
  q.set("since", since);
416
- return (await ctx.client(project)).get(`/api/log?${q}`);
481
+ if (video)
482
+ q.set("video", video);
483
+ return c.get(`/api/log?${q}`);
417
484
  }));
418
485
  server.registerTool("rushes_doctor", {
419
486
  title: "Rushes doctor",
@@ -19,8 +19,10 @@ export const ADAPTERS = {
19
19
  /*
20
20
  * R14/R15: the session mode in which the agent asks Rushes (session/request_permission) before it acts, instead of
21
21
  * approving its own actions. The runner sends session/set_mode with it after every session/new and session/load,
22
- * when the session offers it. Never acceptEdits, auto, bypassPermissions or dontAsk (Claude), nor agent or
23
- * agent-full-access (Codex): in those the agent, or its own reviewer, decides.
22
+ * when the session offers it. Used for Manual and Accept edits, the two rows where Rushes is the gatekeeper. Never
23
+ * acceptEdits, plan or dontAsk (Claude). The modes where the agent, or its own reviewer, decides (Claude's auto and
24
+ * bypassPermissions, Codex's agent and agent-full-access) are used only for the Auto and Bypass rows (§33, AGENT_MODE
25
+ * below), which only the user picks, from the agent menu or the first-Send sheet, never from anything in the project.
24
26
  *
25
27
  * Claude (claude-agent-acp 0.107.3, read 17 Nov 2026):
26
28
  * - dist/session-mode.js:47-48: with no permissions.defaultMode in the user's settings a session starts in `auto`
@@ -60,6 +62,32 @@ export const ASK_MODE = {
60
62
  */
61
63
  codex: "read-only",
62
64
  };
65
+ /*
66
+ * §33: the session mode for each row of the permission menu. Manual and Accept edits use ASK_MODE, so every ask reaches
67
+ * Rushes, which decides by the row and the Always rules (core/agentRules.ts decide). Auto and Bypass hand the decision to
68
+ * the agent; there Rushes is no longer the gatekeeper for .rushes and .git.
69
+ *
70
+ * Checked 19 Nov 2026 against the installed adapters:
71
+ * - Claude (claude-agent-acp 0.107.3, dist/session-mode.js buildAvailableModes): `auto` ("Claude handles permission
72
+ * decisions", offered unless the user's settings disable auto mode) and `bypassPermissions` ("Accepts all
73
+ * permissions", offered unless running as root outside a sandbox or disabled in settings). The CLI's own
74
+ * --permission-mode takes the same two ids. When the session's model can't run auto, the adapter falls back to
75
+ * AUTO_MODE_FALLBACK, `acceptEdits` (dist/session-mode.js:6, effectiveMode): edits go through and commands still ask
76
+ * Rushes. The runner accepts that fallback for Auto and says so in Activity (AUTO_FALLBACK).
77
+ * - Codex (codex-acp 2.7.0, README:76 INITIAL_AGENT_MODE): `agent` (Codex's "Auto review", approvalsReviewer
78
+ * "auto_review") and `agent-full-access` (approvalPolicy "never").
79
+ * A mode the session doesn't offer fails the start closed, as ASK_MODE does (runner.ts agentMode).
80
+ */
81
+ export const AGENT_MODE = {
82
+ "ask-all": ASK_MODE,
83
+ "project-edits": ASK_MODE,
84
+ auto: { claude: "auto", codex: "agent" },
85
+ bypass: { claude: "bypassPermissions", codex: "agent-full-access" },
86
+ };
87
+ /** The mode Claude's adapter falls back to when Auto isn't available for the session's model. Still asks Rushes for commands. */
88
+ export const AUTO_FALLBACK = { claude: "acceptEdits" };
89
+ /** The agent's session mode for a menu row. */
90
+ export const modeFor = (agent, level) => AGENT_MODE[level][agent];
63
91
  /**
64
92
  * clientCapabilities._meta for initialize. Codex (codex-acp 2.7.0, read 18 Nov 2026): a turn that fails on a model or
65
93
  * service error (an unsupported model, an outage) still answers session/prompt with stopReason "end_turn". It says it
@@ -80,12 +108,15 @@ export function clientMeta(agent) {
80
108
  */
81
109
  export const CLAUDE_MODEL = "sonnet";
82
110
  export const CLAUDE_EFFORT = "medium";
83
- /** Extra params for session/new and session/load: Claude's initial mode, so the session is never in `auto` (R14), then its model. */
84
- export function sessionSetup(agent) {
111
+ /**
112
+ * Extra params for session/new and session/load: Claude's initial mode for the row the Send was made under, so the
113
+ * session is never in `auto` unless the user picked Auto (R14, §33), then its model.
114
+ */
115
+ export function sessionSetup(agent, level = "project-edits") {
85
116
  if (agent === "claude") {
86
117
  return {
87
118
  configOptions: [
88
- { configId: "mode", value: ASK_MODE.claude },
119
+ { configId: "mode", value: modeFor("claude", level) },
89
120
  { configId: "model", value: CLAUDE_MODEL },
90
121
  { configId: "effort", value: CLAUDE_EFFORT },
91
122
  ],
@@ -94,7 +125,7 @@ export function sessionSetup(agent) {
94
125
  return {};
95
126
  }
96
127
  /** How to start the ACP adapter for an agent, in the project folder. */
97
- export function adapterSpec(agent, root) {
128
+ export function adapterSpec(agent, root, level = "project-edits") {
98
129
  const { pkg, version } = ADAPTERS[agent.id];
99
130
  // The same PATH detection used, so npx and node are found even when the server has a thin PATH.
100
131
  const env = { PATH: searchPath() };
@@ -102,9 +133,9 @@ export function adapterSpec(agent, root) {
102
133
  env.CLAUDE_CODE_EXECUTABLE = agent.path;
103
134
  if (agent.id === "codex" && agent.path)
104
135
  env.CODEX_PATH = agent.path;
105
- // R15: Codex starts in the mode whose approvals go to Rushes, not to Codex's own reviewer (see ASK_MODE.codex).
136
+ // R15: Codex starts in the mode whose approvals go to Rushes (ASK_MODE.codex), unless the user picked Auto or Bypass (§33).
106
137
  if (agent.id === "codex")
107
- env.INITIAL_AGENT_MODE = ASK_MODE.codex;
138
+ env.INITIAL_AGENT_MODE = modeFor("codex", level);
108
139
  return { command: "npx", args: ["-y", `${pkg}@${version}`], env, cwd: root };
109
140
  }
110
141
  /** This package's built CLI. src/server/agent/ and dist/server/agent/ are both three folders below the package root. */