rushes 0.2.2 → 0.3.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.
@@ -1,4 +1,7 @@
1
1
  import { z } from "zod";
2
+ import { FORMAT_ID_RE, isPictureSize, labelOfId, ratioId, ratioLabel } from "./formats.js";
3
+ import { oneLineOf } from "./labels.js";
4
+ import { LOG_AREAS, LOG_BY, LOG_KINDS, LOG_MAX, LOG_TEXT_MAX } from "./logText.js";
2
5
  export const STAGES = ["script", "picture", "voice", "music", "sfx", "mix"];
3
6
  export const StageSchema = z.enum(STAGES);
4
7
  export const LaneStageSchema = z.enum(["voice", "music", "sfx"]);
@@ -19,16 +22,52 @@ export const ProxySchema = z.object({
19
22
  bytes: z.number().int().nonnegative(),
20
23
  createdAt: z.string(),
21
24
  });
22
- export const VersionSchema = z.object({
25
+ // §21.3: another render of the same cut at another aspect ratio. Its id is its label with ":" as "x".
26
+ export const FormatSchema = z.object({
27
+ id: z.string().max(16).regex(FORMAT_ID_RE),
28
+ label: z.string().min(3).max(16),
29
+ file: z.string().min(1),
30
+ width: z.number().int().positive(),
31
+ height: z.number().int().positive(),
32
+ duration: seconds.nullable().default(null),
33
+ fps: z.number().positive().nullable().default(null),
34
+ addedAt: z.string(),
35
+ });
36
+ export const VersionSchema = z
37
+ .object({
23
38
  id,
24
39
  file: z.string().min(1),
25
40
  duration: seconds.nullable().default(null),
26
41
  fps: z.number().positive().nullable().default(null),
27
42
  addedAt: z.string(),
28
43
  note: z.string().default(""),
44
+ // §22.3: a short label the agent writes, shown in the version list. The 48-character limit is
45
+ // enforced where labels come in (the route, the tool, the CLI). A hand-edited longer one still
46
+ // loads, and shortLabel shows it cut (§22.9, R2). Not the same thing as a format's `label`
47
+ // (its aspect ratio, "9:16").
48
+ label: z.string().default(""),
29
49
  shots: z.array(ShotSchema).max(200).default([]),
30
50
  // §19.5: a lightweight H.264 copy for smooth preview. Set only once a render has completed.
31
51
  proxy: ProxySchema.nullable().default(null),
52
+ // §21.3 (R2): the primary render's picture size as shown, read when the cut is added. Null for a
53
+ // cut from before formats until its first format is registered.
54
+ width: z.number().int().positive().nullable().default(null),
55
+ height: z.number().int().positive().nullable().default(null),
56
+ // §21.3: the other renders of this cut, one per aspect ratio. The primary (`file`) is a format too.
57
+ formats: z.array(FormatSchema).max(8).default([]),
58
+ })
59
+ .superRefine((v, ctx) => {
60
+ // One shape per ratio: no two formats share an id, and none repeats the primary's.
61
+ // A bad width or height is reported by its own field check; the ratio is only worked out for a real size.
62
+ const primary = v.width !== null && v.height !== null && isPictureSize(v.width, v.height) ? ratioId(ratioLabel(v.width, v.height)) : null;
63
+ const seen = new Set(primary ? [primary] : []);
64
+ v.formats.forEach((f, i) => {
65
+ if (f.label !== labelOfId(f.id))
66
+ ctx.addIssue({ code: "custom", path: ["formats", i, "label"], message: `label "${f.label}" doesn't match id "${f.id}"` });
67
+ if (seen.has(f.id))
68
+ ctx.addIssue({ code: "custom", path: ["formats", i, "id"], message: `${v.id} already has ${f.label}` });
69
+ seen.add(f.id);
70
+ });
32
71
  });
33
72
  export const VideoSchema = z.object({
34
73
  id,
@@ -142,6 +181,9 @@ export const NoteSchema = z
142
181
  grab: z.string().nullable().default(null),
143
182
  shot: z.object({ n: z.number().int().positive(), name: z.string() }).nullable().default(null),
144
183
  marks: z.array(MarkSchema).max(4).default([]),
184
+ // §21.3: the format this note belongs to (a Format id such as "9x16"), or null for every format:
185
+ // the default, and every note from before formats. The server checks it against the note's version.
186
+ format: z.string().max(16).regex(FORMAT_ID_RE).nullable().default(null),
145
187
  status: z.enum(["todo", "done"]).default("todo"),
146
188
  reply: z.string().default(""),
147
189
  fixT: seconds.nullable().default(null),
@@ -229,6 +271,90 @@ export const FoundFileSchema = z.object({
229
271
  .max(200)
230
272
  .default([]),
231
273
  });
274
+ // §22.3: the Change Log, .rushes/log.json, oldest first on disk. Written by the server as things
275
+ // happen, created on its first write. Every field is new, so nothing older reads differently.
276
+ export const LogEntrySchema = z.object({
277
+ id,
278
+ at: z.string(),
279
+ area: z.enum(LOG_AREAS),
280
+ kind: z.enum(LOG_KINDS),
281
+ text: z.string().min(1).max(LOG_TEXT_MAX),
282
+ video: z.string().nullable().default(null),
283
+ version: z.string().nullable().default(null),
284
+ ref: z.string().max(300).nullable().default(null),
285
+ by: z.enum(LOG_BY),
286
+ // R3: the tab a Notes line opens, how many events the line stands for, and what a run of them
287
+ // is about (a lane, a section, a film, a folder), so a burst collapses (§22.5).
288
+ tab: StageSchema.nullable().default(null),
289
+ n: z.number().int().positive().default(1),
290
+ subject: z.string().max(200).default(""),
291
+ });
292
+ export const LogFileSchema = z.object({
293
+ schema: z.literal(1),
294
+ rev: z.number().int().nonnegative(),
295
+ // §22.6: set once the dated history has been read in, so it never happens twice.
296
+ backfilled: z.boolean().default(false),
297
+ // M2: when the server that first wrote a line into a log not yet backfilled started. The backfill
298
+ // stops there, since everything after it was logged live (a cut is dated just before its line).
299
+ began: z.string().optional(),
300
+ // R5: the variants and takes already there when the log began ("<lane>/<variant>", "<section>:<take>").
301
+ undated: z.array(z.string().max(300)).max(LOG_MAX).default([]),
302
+ // §22.9: how many lines the 5000 cap has dropped.
303
+ dropped: z.number().int().nonnegative().default(0),
304
+ entries: z.array(LogEntrySchema).max(LOG_MAX).default([]),
305
+ // Set by the tolerant read, never written: a newer Rushes wrote this log (its `schema` is above 1).
306
+ // Its lines can be read, but this Rushes never rewrites the file (final review I2).
307
+ newer: z.literal(true).optional(),
308
+ });
309
+ const isRecord = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
310
+ /**
311
+ * I3, in the spirit of R2: log.json is read tolerantly, so one bad line never loses the log. A line
312
+ * that fails the schema (a hand edit over 160 characters, a kind or an area from a newer Rushes) is
313
+ * left out and counted in `dropped`, as are lines past the newest LOG_MAX (two logs merged by git);
314
+ * undated refs that aren't refs are left out; an id seen twice gets "-2", "-3". The text of a line
315
+ * is read as one clean line (oneLineOf), so a hand edit can't carry a terminal escape, a bidi
316
+ * override or hidden tag characters to anything that prints it. A `rev` that isn't a count reads as
317
+ * 0. A `schema` above 1 is a newer Rushes' log: its lines are read, and `newer` is set so nothing
318
+ * writes the file back. The next write of an ordinary file keeps the cleaned lines. What isn't an
319
+ * object with a list of entries is still corrupt (R7). Writing is checked against LogFileSchema as
320
+ * strictly as ever.
321
+ */
322
+ function tolerantLog(raw) {
323
+ if (!isRecord(raw) || !Array.isArray(raw.entries))
324
+ return raw;
325
+ const entries = [];
326
+ const ids = new Set();
327
+ let bad = 0;
328
+ for (const item of raw.entries) {
329
+ const line = LogEntrySchema.safeParse(isRecord(item) ? cleanLine(item) : item);
330
+ if (!line.success) {
331
+ bad += 1;
332
+ continue;
333
+ }
334
+ let id = line.data.id;
335
+ for (let k = 2; ids.has(id); k++)
336
+ id = `${line.data.id.slice(0, 58)}-${k}`;
337
+ ids.add(id);
338
+ entries.push({ ...line.data, id });
339
+ }
340
+ const over = Math.max(0, entries.length - LOG_MAX);
341
+ const dropped = typeof raw.dropped === "number" && Number.isInteger(raw.dropped) && raw.dropped >= 0 ? raw.dropped : 0;
342
+ const undated = Array.isArray(raw.undated) ? raw.undated.filter((r) => typeof r === "string" && r.length <= 300).slice(0, LOG_MAX) : raw.undated;
343
+ const rev = typeof raw.rev === "number" && Number.isInteger(raw.rev) && raw.rev >= 0 ? raw.rev : 0;
344
+ const newer = typeof raw.schema === "number" && Number.isInteger(raw.schema) && raw.schema > 1;
345
+ return { ...raw, schema: 1, rev, newer: newer ? true : undefined, undated, dropped: dropped + bad + over, entries: entries.slice(over) };
346
+ }
347
+ /** A stored line with its words made one clean line. What isn't text is left for the schema to refuse. */
348
+ function cleanLine(item) {
349
+ const out = { ...item };
350
+ if (typeof out.text === "string")
351
+ out.text = oneLineOf(out.text);
352
+ if (typeof out.subject === "string")
353
+ out.subject = oneLineOf(out.subject);
354
+ return out;
355
+ }
356
+ /** How log.json is read (see tolerantLog); the store writes it against LogFileSchema. */
357
+ export const LogFileReadSchema = z.preprocess(tolerantLog, LogFileSchema);
232
358
  export const FILES = {
233
359
  project: { name: "project.json", schema: ProjectSchema },
234
360
  script: { name: "script.json", schema: ScriptSchema },
@@ -236,4 +362,5 @@ export const FILES = {
236
362
  picks: { name: "picks.json", schema: PicksSchema },
237
363
  batches: { name: "batches.json", schema: BatchesFileSchema },
238
364
  found: { name: "found.json", schema: FoundFileSchema },
365
+ log: { name: "log.json", schema: LogFileSchema, read: LogFileReadSchema },
239
366
  };
@@ -4,7 +4,7 @@ import { join } from "node:path";
4
4
  import { FILES } from "./schema.js";
5
5
  import { CorruptFileError, InvalidError, RevConflictError } from "./errors.js";
6
6
  export const RUSHES_DIR = ".rushes";
7
- const GITIGNORE = "proxies/\npeaks/\nserver.json\nserver.log\n*.tmp\n*.bak\n";
7
+ const GITIGNORE = "proxies/\npeaks/\nserver.json\nserver.log\nlog.json.bad*\n*.tmp\n*.bak\n";
8
8
  function defaults(key, name) {
9
9
  switch (key) {
10
10
  case "project":
@@ -19,13 +19,15 @@ function defaults(key, name) {
19
19
  return { schema: 1, rev: 0, batches: [] };
20
20
  case "found":
21
21
  return { schema: 1, rev: 0, dismissed: [], settled: [] };
22
+ case "log":
23
+ return { schema: 1, rev: 0, backfilled: false, undated: [], dropped: 0, entries: [] };
22
24
  }
23
25
  }
24
26
  /**
25
- * Files `init` doesn't write. Each is created by its first write, and reads as its default until
26
- * then, so a project made before the file existed needs nothing done to it.
27
+ * Files `init` doesn't write (found.json, log.json). Each is created by its first write, and reads
28
+ * as its default until then, so a project made before the file existed needs nothing done to it.
27
29
  */
28
- const CREATED_ON_WRITE = new Set(["found"]);
30
+ const CREATED_ON_WRITE = new Set(["found", "log"]);
29
31
  /**
30
32
  * The only writer of a project's .rushes folder. Every write is validated,
31
33
  * serialised per file, written atomically (tmp + rename) and announced with
@@ -75,7 +77,9 @@ export class Store extends EventEmitter {
75
77
  catch (e) {
76
78
  throw new CorruptFileError(file, `invalid JSON (${e.message})`);
77
79
  }
78
- const parsed = FILES[key].schema.safeParse(json);
80
+ // A file may be read more leniently than it's written (log.json, I3).
81
+ const def = FILES[key];
82
+ const parsed = ("read" in def ? def.read : def.schema).safeParse(json);
79
83
  if (!parsed.success)
80
84
  throw new CorruptFileError(file, parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "));
81
85
  return parsed.data;
package/dist/mcp/tools.js CHANGED
@@ -3,6 +3,8 @@ import { z } from "zod";
3
3
  import { ApiError, dashboardUrlFor } from "./client.js";
4
4
  import { VERSION } from "../server/app.js";
5
5
  import { BRING_IN_MAX } from "../server/found.js";
6
+ import { LABEL_MAX, oneLineOf } from "../core/labels.js";
7
+ import { LOG_AREAS } from "../core/logText.js";
6
8
  const project = z.string().optional().describe("Project folder. Defaults to the current working directory.");
7
9
  const stage = z.enum(["script", "picture", "voice", "music", "sfx", "mix"]);
8
10
  const fileKind = z.enum(["doc", "image", "caption", "export", "delivery", "edit"]);
@@ -14,6 +16,19 @@ const bringInItem = z.object({
14
16
  kind: z.enum(["voice", "music", "sfx", "cut", "doc"]).optional(),
15
17
  round: z.string().trim().min(1).max(64).optional().describe('Voice only: the round the read joins, e.g. "Round 2 · Gerald, tone". Defaults to its folder\'s name.'),
16
18
  });
19
+ // §21.4: the server's own limits on formats (src/server/app.ts), so a request that can't land is refused here, in words.
20
+ const FORMAT_PATH_MAX = 1024;
21
+ const FORMAT_ID_MAX = 16;
22
+ const FORMAT_LABEL_MAX = 16;
23
+ // A format id ("9x16", "2.39x1"), or the label it is written from ("9:16"): the id has an x where the label has a colon.
24
+ const FORMAT_ID_OR_LABEL = /^\d+(?:\.\d+)?[x:]\d+(?:\.\d+)?$/;
25
+ const FORMATS_BESIDE_CUT_MAX = 7;
26
+ // What an agent is told when a Rushes started by an older version quietly ignores the new fields.
27
+ const OLDER_DROPPED = "An older Rushes is running and ignored `formats`: the cut is in, its other shapes are not. Run `rushes stop`, then add them with rushes_add_format.";
28
+ const OLDER_DROPPED_LABEL = "An older Rushes is running and dropped the label: the cut was added without it. Run `rushes stop`, then open again.";
29
+ // A 0.2.x Rushes drops both: one note that says both, so neither is lost.
30
+ const OLDER_DROPPED_BOTH = "An older Rushes is running and dropped the label and ignored `formats`: the cut is in, without its label and without its other shapes. Run `rushes stop`, then open again and add the shapes with rushes_add_format.";
31
+ const OLDER_UNFILTERED = "An older Rushes is running and ignores `format`: these are every note, not that format's. Run `rushes stop`, then ask again.";
17
32
  function ok(data) {
18
33
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
19
34
  }
@@ -136,14 +151,57 @@ export function createMcpServer(ctx) {
136
151
  }, safe(async ({ project }) => (await ctx.client(project)).get("/api/tabs")));
137
152
  server.registerTool("rushes_add_version", {
138
153
  title: "Add a cut",
139
- 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.",
154
+ 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).",
140
155
  inputSchema: {
141
156
  project,
142
157
  video: z.string().describe("Video id or name, e.g. \"Hero 60s\"."),
143
158
  file: z.string().describe("Path to the rendered file, absolute or relative to the project."),
144
159
  note: z.string().optional().describe("What changed in this cut."),
160
+ label: z
161
+ .string()
162
+ // Counted as the route counts it: on one clean line (padding and invisible characters don't count), in characters.
163
+ .refine((s) => Array.from(oneLineOf(s)).length <= LABEL_MAX, `label is ${LABEL_MAX} characters at most: put the detail in note`)
164
+ // Still advertised, so an agent sees the limit in the schema.
165
+ .meta({ maxLength: LABEL_MAX })
166
+ .optional()
167
+ .describe(`A short label for the version list, ${LABEL_MAX} characters at most, e.g. "launch 1.45x slower". The detail goes in note.`),
168
+ formats: z
169
+ .array(z.object({ file: z.string().min(1).max(FORMAT_PATH_MAX) }))
170
+ .max(FORMATS_BESIDE_CUT_MAX)
171
+ .optional()
172
+ .describe("Other shapes of this same cut (the same edit at other aspect ratios, e.g. a 9:16 and a 1:1 of the 16:9), registered as its formats in one call. `file` is the main one."),
173
+ },
174
+ }, safe(async ({ project, ...b }) => {
175
+ const r = await (await ctx.client(project)).post("/api/versions", b);
176
+ // A Rushes started by an older version ignores `label`, and its reply has none; one from before
177
+ // formats drops `formats` without a word. Say which, so the agent isn't left thinking either was kept.
178
+ const droppedLabel = Boolean(b.label && r?.version && r.version.label === undefined);
179
+ const droppedFormats = Boolean(b.formats?.length && r?.version && !Array.isArray(r.version.formats));
180
+ if (droppedLabel && droppedFormats)
181
+ return { ...r, note: OLDER_DROPPED_BOTH };
182
+ if (droppedLabel)
183
+ return { ...r, note: OLDER_DROPPED_LABEL };
184
+ if (droppedFormats)
185
+ return { ...r, note: OLDER_DROPPED };
186
+ return r;
187
+ }));
188
+ server.registerTool("rushes_add_format", {
189
+ title: "Add a format",
190
+ description: "Register another shape of a cut: the same edit rendered at another aspect ratio, e.g. the 9:16 or 1:1 of a 16:9 cut. Rushes measures the ratio with ffprobe. Defaults to the newest cut of the only or newest film. Returns the format's id and label (e.g. \"9x16\", \"9:16\"), and `warning` when its length is more than 0.1 s off the cut's. Refused, with the reason: a second render with a ratio the cut already has (a re-render is a new version), a file that isn't a video, a cut that already has 8 shapes (the most one cut can have, its own file included), and a machine without ffprobe. The cut's own file stays its main shape: register only the other shapes.",
191
+ inputSchema: {
192
+ project,
193
+ video: z.string().min(1).max(200).optional().describe("Video id or name. Defaults to the newest cut's film."),
194
+ version: z.string().min(1).max(64).optional().describe("Defaults to that film's newest cut."),
195
+ file: z.string().min(1).max(FORMAT_PATH_MAX).describe("Path to the render, absolute or relative to the project."),
196
+ label: z
197
+ .string()
198
+ .trim()
199
+ .min(1)
200
+ .max(FORMAT_LABEL_MAX)
201
+ .optional()
202
+ .describe('A ratio hint only, e.g. "2.39:1", used when the measured ratio isn\'t a standard one. Not the cut\'s short label (that is `label` on rushes_add_version).'),
145
203
  },
146
- }, safe(async ({ project, ...b }) => (await ctx.client(project)).post("/api/versions", b)));
204
+ }, safe(async ({ project, ...b }) => (await ctx.client(project)).post("/api/formats", b)));
147
205
  server.registerTool("rushes_add_variant", {
148
206
  title: "Add an audio variant",
149
207
  description: "Add a voice read (in a round), music bed or SFX pass for side-by-side review. Returns its lane and variant ids: a note on it is `on` \"<lane id>/<variant id>\".",
@@ -191,17 +249,30 @@ export function createMcpServer(ctx) {
191
249
  }, safe(async ({ project, section, file }) => (await ctx.client(project)).post(`/api/script/${encodeURIComponent(section)}/takes`, { file })));
192
250
  server.registerTool("rushes_list_notes", {
193
251
  title: "List notes",
194
- description: "Notes left in Rushes, filtered by tab, status, batch or version. 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.",
252
+ description: "Notes left in Rushes, filtered by tab, status, batch or version. 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.",
195
253
  inputSchema: {
196
254
  project,
197
255
  stage: stage.optional(),
198
256
  status: z.enum(["todo", "done"]).optional(),
199
257
  batch: z.string().optional(),
200
258
  version: z.string().optional(),
259
+ format: z
260
+ .string()
261
+ .max(FORMAT_ID_MAX)
262
+ .regex(FORMAT_ID_OR_LABEL)
263
+ .optional()
264
+ .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.'),
265
+ onlyThisFormat: z.boolean().optional().describe("With format: only that format's notes, not the all-format ones."),
201
266
  },
202
267
  }, safe(async ({ project, ...f }) => {
203
- const q = new URLSearchParams(Object.entries(f).filter(([, v]) => v !== undefined));
204
- return (await ctx.client(project)).get(`/api/notes${q.size ? `?${q}` : ""}`);
268
+ // The label "9:16" is the format "9x16".
269
+ const asked = { ...f, ...(f.format !== undefined ? { format: f.format.replace(":", "x") } : {}) };
270
+ const q = new URLSearchParams(Object.entries(asked).filter(([, v]) => v !== undefined).map(([k, v]) => [k, String(v)]));
271
+ const r = await (await ctx.client(project)).get(`/api/notes${q.size ? `?${q}` : ""}`);
272
+ // A Rushes from before formats ignores the filter and sends every note, none with a `format`.
273
+ if (f.format !== undefined && Array.isArray(r?.notes) && r.notes.some((n) => !("format" in n)))
274
+ return { ...r, note: OLDER_UNFILTERED };
275
+ return r;
205
276
  }));
206
277
  server.registerTool("rushes_get_batch", {
207
278
  title: "Get a batch",
@@ -248,9 +319,39 @@ export function createMcpServer(ctx) {
248
319
  }, safe(async ({ project, ...b }) => (await ctx.client(project)).post("/api/files", b)));
249
320
  server.registerTool("rushes_export_notes", {
250
321
  title: "Export notes",
251
- description: "Write every note to exports/<project-slug>-notes-<date>.md, grouped by stage and, for Picture, by film and version. Exporting again the same day overwrites it. Returns the path.",
322
+ description: "Write every note to exports/<project-slug>-notes-<date>.md, grouped by stage and, for Picture, by film and version, and the Change Log to exports/change-log-<date>.md, newest first. Exporting again the same day overwrites them. Returns both paths (path, changeLog).",
252
323
  inputSchema: { project },
253
324
  }, safe(async ({ project }) => (await ctx.client(project)).post("/api/exports/notes", {})));
325
+ const area = z.enum(LOG_AREAS);
326
+ server.registerTool("rushes_log", {
327
+ title: "Add a line to the Change Log",
328
+ description: 'Adds one line to the project\'s Change Log, as the agent: a decision or a change of direction, e.g. "Slowed the zooms: the first cut felt rushed". One line, 160 characters at most (longer is cut): one line per decision, not a running commentary. The log is exported and shared, so never copy a note\'s or reply\'s text into it. Rushes already logs cuts, formats (another shape of a cut), voice reads, music, sound effects, takes, the script, picks, picture lock and unlock, notes sent, replies, files added and bring-ins by itself, so don\'t repeat those. `area` defaults to project; `video`, `version` and `ref` ("<lane>/<variant>" or "<section>:<take>") let the line open that place in the dashboard. Returns the line.',
329
+ inputSchema: {
330
+ project,
331
+ text: z.string().min(1).max(2000).describe("What happened, in one line."),
332
+ area: area.optional().describe("script, picture, voice, music, sfx, mix, notes, assets or project (the default)."),
333
+ video: z.string().min(1).max(200).optional().describe("Video id or name, to open its cut from the line."),
334
+ version: z.string().min(1).max(64).optional().describe("With video: the version to open."),
335
+ ref: z.string().min(1).max(300).optional().describe('"<lane>/<variant>" to open a voice read, bed or pass from the line, or "<section>:<take>" for a take.'),
336
+ },
337
+ }, safe(async ({ project, ...b }) => (await ctx.client(project)).post("/api/log", b)));
338
+ server.registerTool("rushes_get_log", {
339
+ title: "Read the Change Log",
340
+ 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).",
341
+ inputSchema: {
342
+ project,
343
+ limit: z.number().int().min(1).max(200).default(30).describe("How many lines, newest first. Default 30, at most 200."),
344
+ area: area.optional().describe("Only this area."),
345
+ since: z.string().optional().describe("Only lines after this date and time, e.g. 2026-10-07T09:00:00Z."),
346
+ },
347
+ }, safe(async ({ project, limit, area: a, since }) => {
348
+ const q = new URLSearchParams({ limit: String(limit ?? 30) });
349
+ if (a)
350
+ q.set("area", a);
351
+ if (since)
352
+ q.set("since", since);
353
+ return (await ctx.client(project)).get(`/api/log?${q}`);
354
+ }));
254
355
  server.registerTool("rushes_doctor", {
255
356
  title: "Rushes doctor",
256
357
  description: "Health check (§19.3): Node version, ffmpeg/ffprobe on PATH, which agent harnesses have the Rushes MCP server registered, and this project's files, server and disk space. Read-only -- doesn't start a server or change anything.",