rushes 0.10.1 → 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.
Files changed (41) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/AGENTS.md +14 -4
  3. package/README.md +14 -8
  4. package/dist/cli/demo.js +3 -2
  5. package/dist/cli/main.js +33 -1
  6. package/dist/core/agentRules.js +7 -0
  7. package/dist/core/balance.js +238 -0
  8. package/dist/core/batches.js +29 -11
  9. package/dist/core/exportNotes.js +4 -2
  10. package/dist/core/films.js +114 -0
  11. package/dist/core/log.js +35 -3
  12. package/dist/core/logEvents.js +7 -7
  13. package/dist/core/notes.js +19 -1
  14. package/dist/core/schema.js +69 -14
  15. package/dist/core/script.js +67 -0
  16. package/dist/core/tabs.js +15 -7
  17. package/dist/core/takes.js +1 -1
  18. package/dist/mcp/tools.js +90 -23
  19. package/dist/server/agent/adapters.js +39 -8
  20. package/dist/server/agent/rules.js +106 -9
  21. package/dist/server/agent/runner.js +135 -35
  22. package/dist/server/agent/setupOnce.js +44 -0
  23. package/dist/server/app.js +348 -65
  24. package/dist/server/assets.js +40 -14
  25. package/dist/server/balance.js +103 -0
  26. package/dist/server/brief.js +9 -7
  27. package/dist/server/files.js +3 -2
  28. package/dist/server/films.js +43 -0
  29. package/dist/server/found.js +2 -1
  30. package/dist/server/logbook.js +28 -2
  31. package/dist/server/plans.js +68 -0
  32. package/dist/server/record.js +31 -13
  33. package/dist/server/start.js +15 -7
  34. package/dist/server/storyboard.js +8 -6
  35. package/dist/version.js +1 -1
  36. package/package.json +1 -1
  37. package/skills/rushes/SKILL.md +4 -4
  38. package/web-dist/assets/{index-BIJlv6zN.css → index-BCYA0Awp.css} +1 -1
  39. package/web-dist/assets/index-LPvsS2vO.js +70 -0
  40. package/web-dist/index.html +2 -2
  41. package/web-dist/assets/index-D430jOsg.js +0 -70
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. */
@@ -1,5 +1,7 @@
1
1
  // R10: what the agent may do without asking (permissions and Always rules) is kept per user, outside the project,
2
- // so an agent working in the project can never grant itself a rule by editing a file there. So are the user's answer to
2
+ // so an agent working in the project can never grant itself a rule by editing a file there. §33: that includes the
3
+ // Auto and Bypass rows, in which the agent's own mode decides and Rushes no longer guards .rushes and .git: they are
4
+ // chosen only by the user, in the agent menu or the first-Send sheet, never from anything in the project. So are the user's answer to
3
5
  // the first-Send sheet (I1, `setUp`) and the agent they chose (`agent`): a project folder from someone else, or anything
4
6
  // that writes the project, can't turn Send to AI on for an agent.
5
7
  //
@@ -8,12 +10,17 @@
8
10
  // key: the first 16 hex characters of sha256(realpath.native(project root)), the name as the volume stores it
9
11
  //
10
12
  // The folder is 0700 and the file 0600. Writes are serialised and atomic (tmp + rename), like the project's own files.
13
+ //
14
+ // §32: Send to AI is set up once per Mac. Beside that folder is the Mac-wide default, <user config dir>/rushes/agent-
15
+ // defaults.json: `{ agent, permissions }`, the user's last choice in the first-Send sheet, the agent menu or the switch
16
+ // turned on. A project with no rules file yet starts from it (AgentRulesFile.adopt). It is the user's own file, outside
17
+ // every project, so R10 holds: nothing inside a project can write it, or grant itself anything through it.
11
18
  import { createHash } from "node:crypto";
12
19
  import { realpathSync } from "node:fs";
13
- import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
20
+ import { chmod, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
14
21
  import { homedir } from "node:os";
15
22
  import { dirname, isAbsolute, join } from "node:path";
16
- import { AgentRulesReadSchema, AgentRulesSchema } from "../../core/schema.js";
23
+ import { AgentDefaultsSchema, AgentRulesReadSchema, AgentRulesSchema } from "../../core/schema.js";
17
24
  import { InvalidError } from "../../core/errors.js";
18
25
  /** $XDG_CONFIG_HOME when set to an absolute path (as the XDG spec asks), else ~/.config. Tests point it at a temp folder. */
19
26
  export function userConfigDir(env = process.env) {
@@ -81,17 +88,107 @@ export class AgentRulesFile {
81
88
  const checked = AgentRulesSchema.safeParse(draft);
82
89
  if (!checked.success)
83
90
  throw new InvalidError("Change to the agent's rules is invalid", checked.error.issues);
84
- const dir = dirname(this.path);
85
- await mkdir(dir, { recursive: true, mode: 0o700 });
86
- await chmod(dir, 0o700);
87
- const tmp = `${this.path}.${process.pid}.${Date.now()}.${++writes}.tmp`;
88
- await writeFile(tmp, JSON.stringify(checked.data, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
89
- await rename(tmp, this.path);
91
+ await writePrivate(this.path, checked.data);
90
92
  return { data: checked.data, result };
91
93
  });
92
94
  this.queue = run;
93
95
  return run;
94
96
  }
97
+ /**
98
+ * §32: a project with no rules file yet starts from the Mac-wide default: set up, the default agent (none after Copy
99
+ * a prompt), the default permissions and no Always rules. Written in the queue and only while there is still no file,
100
+ * so it never overwrites rules made meanwhile. Null when the file was there already, or there is no default.
101
+ */
102
+ adopt(defaults) {
103
+ const run = this.queue.catch(() => undefined).then(async () => {
104
+ if (!defaults || (await exists(this.path)))
105
+ return null;
106
+ // §33: Bypass is never adopted: a new project whose default is Bypass starts in Accept edits. Auto is adopted.
107
+ const permissions = defaults.permissions === "bypass" ? "project-edits" : defaults.permissions;
108
+ const rules = AgentRulesSchema.parse({ setUp: true, agent: defaults.agent, permissions, always: [] });
109
+ await writePrivate(this.path, rules);
110
+ return rules;
111
+ });
112
+ this.queue = run;
113
+ return run;
114
+ }
115
+ }
116
+ async function exists(path) {
117
+ try {
118
+ await stat(path);
119
+ return true;
120
+ }
121
+ catch (e) {
122
+ if (e.code === "ENOENT")
123
+ return false;
124
+ throw e;
125
+ }
126
+ }
127
+ /** Writes JSON the user's own way: its folder 0700, the file 0600, atomically (tmp + rename). */
128
+ async function writePrivate(path, data) {
129
+ const dir = dirname(path);
130
+ await mkdir(dir, { recursive: true, mode: 0o700 });
131
+ await chmod(dir, 0o700);
132
+ const tmp = `${path}.${process.pid}.${Date.now()}.${++writes}.tmp`;
133
+ await writeFile(tmp, JSON.stringify(data, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
134
+ await rename(tmp, path);
135
+ }
136
+ /** §32: where the Mac-wide default is: <user config dir>/rushes/agent-defaults.json. */
137
+ export function defaultsPath(configDir = userConfigDir()) {
138
+ return join(configDir, "rushes", "agent-defaults.json");
139
+ }
140
+ /** §32: Send to AI's Mac-wide default. One per config dir, so every project's writes to it queue together. */
141
+ export class AgentDefaultsFile {
142
+ path;
143
+ queue = Promise.resolve();
144
+ constructor(configDir = userConfigDir()) {
145
+ this.path = defaultsPath(configDir);
146
+ }
147
+ /** The default, or null when there is none yet (the sheet asks once). A damaged file is no default: the sheet asks. */
148
+ async read() {
149
+ let raw;
150
+ try {
151
+ raw = await readFile(this.path, "utf8");
152
+ }
153
+ catch (e) {
154
+ if (e.code !== "ENOENT")
155
+ console.error(`Rushes: couldn't read Send to AI's default at ${this.path}: ${e.message}.`);
156
+ return null;
157
+ }
158
+ try {
159
+ const parsed = AgentDefaultsSchema.safeParse(JSON.parse(raw));
160
+ if (parsed.success)
161
+ return parsed.data;
162
+ }
163
+ catch {
164
+ /* damaged: below */
165
+ }
166
+ console.error(`Rushes: Send to AI's default at ${this.path} is damaged. A new project asks who gets the notes until it is saved again.`);
167
+ return null;
168
+ }
169
+ /**
170
+ * Last choice wins: writes what the user just chose (an agent, null after Copy a prompt, or the permissions) and keeps
171
+ * the rest. With no default yet, the rest comes from `base` (the project's rules as they are now).
172
+ */
173
+ set(change, base) {
174
+ const run = this.queue.catch(() => undefined).then(async () => {
175
+ const next = AgentDefaultsSchema.parse({ ...((await this.read()) ?? base), ...change });
176
+ await writePrivate(this.path, next);
177
+ return next;
178
+ });
179
+ this.queue = run;
180
+ return run;
181
+ }
182
+ }
183
+ const defaultFiles = new Map();
184
+ /** The Mac-wide default's file for the user config dir now (tests point XDG_CONFIG_HOME at a temp folder). */
185
+ export function agentDefaultsFile(configDir = userConfigDir()) {
186
+ let f = defaultFiles.get(configDir);
187
+ if (!f) {
188
+ f = new AgentDefaultsFile(configDir);
189
+ defaultFiles.set(configDir, f);
190
+ }
191
+ return f;
95
192
  }
96
193
  const files = new WeakMap();
97
194
  /** The one rules file for `store`'s project, shared by the runner and the routes so their writes queue together. */