@dudamel/mcp-agents 2026.1112.1 → 2026.1117.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -51,12 +51,20 @@ var DudamelApiError = class extends Error {
51
51
  var DudamelApiClient = class {
52
52
  baseUrl;
53
53
  headers;
54
- constructor(baseUrl, apiKey, authScheme) {
54
+ /**
55
+ * `extraHeaders` go on every request — the memory MCP sends `x-dudamel-private-conversation`
56
+ * there when the worker said the turn is private, never anything an agent chose.
57
+ */
58
+ constructor(baseUrl, apiKey, authScheme, extraHeaders) {
55
59
  this.baseUrl = baseUrl.replace(/\/+$/, "");
56
60
  this.headers = {
61
+ ...extraHeaders,
57
62
  Authorization: `${authScheme ?? "ApiKey"} ${apiKey}`,
58
63
  "Content-Type": "application/json"
59
64
  };
65
+ const proposalTest = process.env["DUDAMEL_PROPOSAL_TEST"]?.trim();
66
+ if (proposalTest)
67
+ this.headers["x-dudamel-proposal-test"] = proposalTest;
60
68
  }
61
69
  async get(path, params) {
62
70
  const url = this.buildUrl(path, params);
@@ -76,10 +84,28 @@ var DudamelApiClient = class {
76
84
  body: body !== void 0 ? JSON.stringify(body) : void 0
77
85
  });
78
86
  }
87
+ async patch(path, body, params) {
88
+ const url = this.buildUrl(path, params);
89
+ return this.request(url, {
90
+ method: "PATCH",
91
+ body: body !== void 0 ? JSON.stringify(body) : void 0
92
+ });
93
+ }
79
94
  async delete(path, params) {
80
95
  const url = this.buildUrl(path, params);
81
96
  return this.request(url, { method: "DELETE" });
82
97
  }
98
+ /**
99
+ * A request whose answer depends on its status, not only on its body: a reviewed write
100
+ * answers `202 {proposal}` when it became a proposal and its usual 2xx when it applied
101
+ * directly. Throws {@link DudamelApiError} on a non-2xx, like the other methods.
102
+ */
103
+ async send(method, path, body) {
104
+ return this.exchange(this.buildUrl(path), {
105
+ method,
106
+ body: body !== void 0 ? JSON.stringify(body) : void 0
107
+ });
108
+ }
83
109
  buildUrl(path, params) {
84
110
  const url = new URL(path, this.baseUrl);
85
111
  if (params) {
@@ -92,6 +118,9 @@ var DudamelApiClient = class {
92
118
  return url.toString();
93
119
  }
94
120
  async request(url, init) {
121
+ return (await this.exchange(url, init)).data;
122
+ }
123
+ async exchange(url, init) {
95
124
  const response = await fetch(url, {
96
125
  ...init,
97
126
  headers: this.headers
@@ -101,10 +130,7 @@ var DudamelApiClient = class {
101
130
  throw new DudamelApiError(response.status, response.statusText, body);
102
131
  }
103
132
  const text = await response.text();
104
- if (!text) {
105
- return void 0;
106
- }
107
- return JSON.parse(text);
133
+ return { status: response.status, data: text ? JSON.parse(text) : void 0 };
108
134
  }
109
135
  };
110
136
 
@@ -188,10 +214,501 @@ function registerOwnerTools(kinds) {
188
214
  };
189
215
  }
190
216
 
217
+ // ../common/dist/proposals.js
218
+ import { z as z2 } from "zod";
219
+
220
+ // ../common/dist/text-diff.js
221
+ var MAX_CELLS = 4e6;
222
+ function splitLines(text) {
223
+ if (text === "")
224
+ return [];
225
+ const lines = text.split("\n");
226
+ if (lines[lines.length - 1] === "")
227
+ lines.pop();
228
+ return lines;
229
+ }
230
+ function lineOps(a, b) {
231
+ let head = 0;
232
+ while (head < a.length && head < b.length && a[head] === b[head])
233
+ head += 1;
234
+ let tail = 0;
235
+ while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail]) {
236
+ tail += 1;
237
+ }
238
+ const x = a.slice(head, a.length - tail);
239
+ const y = b.slice(head, b.length - tail);
240
+ const ops = a.slice(0, head).map((line) => ({ kind: " ", line }));
241
+ if (x.length * y.length > MAX_CELLS) {
242
+ ops.push(...x.map((line) => ({ kind: "-", line })));
243
+ ops.push(...y.map((line) => ({ kind: "+", line })));
244
+ } else {
245
+ const w = y.length + 1;
246
+ const lengths = new Uint32Array((x.length + 1) * w);
247
+ for (let i2 = x.length - 1; i2 >= 0; i2 -= 1) {
248
+ for (let j2 = y.length - 1; j2 >= 0; j2 -= 1) {
249
+ lengths[i2 * w + j2] = x[i2] === y[j2] ? (lengths[(i2 + 1) * w + j2 + 1] ?? 0) + 1 : Math.max(lengths[(i2 + 1) * w + j2] ?? 0, lengths[i2 * w + j2 + 1] ?? 0);
250
+ }
251
+ }
252
+ let i = 0;
253
+ let j = 0;
254
+ while (i < x.length && j < y.length) {
255
+ if (x[i] === y[j]) {
256
+ ops.push({ kind: " ", line: x[i] ?? "" });
257
+ i += 1;
258
+ j += 1;
259
+ } else if ((lengths[(i + 1) * w + j] ?? 0) >= (lengths[i * w + j + 1] ?? 0)) {
260
+ ops.push({ kind: "-", line: x[i] ?? "" });
261
+ i += 1;
262
+ } else {
263
+ ops.push({ kind: "+", line: y[j] ?? "" });
264
+ j += 1;
265
+ }
266
+ }
267
+ for (; i < x.length; i += 1)
268
+ ops.push({ kind: "-", line: x[i] ?? "" });
269
+ for (; j < y.length; j += 1)
270
+ ops.push({ kind: "+", line: y[j] ?? "" });
271
+ }
272
+ ops.push(...a.slice(a.length - tail).map((line) => ({ kind: " ", line })));
273
+ return ops;
274
+ }
275
+ function unifiedDiff(before, after, context = 3) {
276
+ const ops = lineOps(splitLines(before), splitLines(after));
277
+ const changed = ops.map((op, index) => op.kind === " " ? -1 : index).filter((i) => i >= 0);
278
+ if (changed.length === 0)
279
+ return "";
280
+ const ranges = [];
281
+ for (const index of changed) {
282
+ const start = Math.max(0, index - context);
283
+ const end = Math.min(ops.length - 1, index + context);
284
+ const last = ranges[ranges.length - 1];
285
+ if (last && start <= last[1] + 1)
286
+ last[1] = Math.max(last[1], end);
287
+ else
288
+ ranges.push([start, end]);
289
+ }
290
+ const oldAt = [];
291
+ const newAt = [];
292
+ let oldLine = 1;
293
+ let newLine = 1;
294
+ for (const op of ops) {
295
+ oldAt.push(oldLine);
296
+ newAt.push(newLine);
297
+ if (op.kind !== "+")
298
+ oldLine += 1;
299
+ if (op.kind !== "-")
300
+ newLine += 1;
301
+ }
302
+ const out = [];
303
+ for (const [start, end] of ranges) {
304
+ const slice = ops.slice(start, end + 1);
305
+ const oldCount = slice.filter((op) => op.kind !== "+").length;
306
+ const newCount = slice.filter((op) => op.kind !== "-").length;
307
+ const oldStart = oldCount === 0 ? (oldAt[start] ?? 1) - 1 : oldAt[start] ?? 1;
308
+ const newStart = newCount === 0 ? (newAt[start] ?? 1) - 1 : newAt[start] ?? 1;
309
+ out.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
310
+ for (const op of slice)
311
+ out.push(`${op.kind}${op.line}`);
312
+ }
313
+ return out.join("\n");
314
+ }
315
+
316
+ // ../common/dist/proposals.js
317
+ var PROPOSAL_ARG_HELP = "The proposal this change goes into. A workflow, agent or skill of a role changes only through a published proposal, so this is needed for every resource of a role. `{title, description}` opens a new one (title and description are what the history keeps: say what changes and why); it stays a draft only its author sees unless `draft: false`, which opens it for review right away. `{id}` adds this change to one of your own drafts or open proposals (same role). System resources have no role: they are not proposed.";
318
+ var proposalArg = z2.object({
319
+ id: z2.string().optional().describe("An existing proposal of yours (draft or open)"),
320
+ title: z2.string().optional().describe("Title of a new proposal"),
321
+ description: z2.string().optional().describe("What changes and why, for the people who review it"),
322
+ draft: z2.boolean().optional().describe("New proposal only. Defaults to true (a draft); false opens it for review")
323
+ }).optional().describe(PROPOSAL_ARG_HELP);
324
+ function toProposalTarget(arg) {
325
+ if (!arg)
326
+ return void 0;
327
+ if (arg.id !== void 0) {
328
+ if (arg.title !== void 0 || arg.description !== void 0 || arg.draft !== void 0) {
329
+ throw new Error("proposal is either {id} (an existing proposal) or {title, description, draft?} (a new one), not both.");
330
+ }
331
+ return { id: arg.id };
332
+ }
333
+ if (arg.title === void 0 && arg.description === void 0)
334
+ return void 0;
335
+ return { title: arg.title ?? "", description: arg.description ?? "", draft: arg.draft ?? true };
336
+ }
337
+ function withProposal(body, arg) {
338
+ const target = toProposalTarget(arg);
339
+ return target ? { ...body, proposal: target } : body;
340
+ }
341
+ async function reviewedWrite(client, method, path, body, arg) {
342
+ const res = await client.send(method, path, withProposal(body, arg));
343
+ if (res.status === 202) {
344
+ return { kind: "proposed", proposal: res.data.proposal };
345
+ }
346
+ return { kind: "direct", result: res.data };
347
+ }
348
+ function reviewedResult(out, direct = (result) => result) {
349
+ return jsonResult(out.kind === "proposed" ? proposalReceipt(out.proposal) : direct(out.result));
350
+ }
351
+ function changedFiles(change) {
352
+ const base = new Map(change.baseFiles.map((f) => [f.path, f]));
353
+ const out = [];
354
+ for (const file of change.files) {
355
+ const before = base.get(file.path);
356
+ base.delete(file.path);
357
+ if (!before)
358
+ out.push({ path: file.path, status: "added" });
359
+ else if (before.content !== file.content || before.encoding !== file.encoding) {
360
+ out.push({ path: file.path, status: "modified" });
361
+ }
362
+ }
363
+ for (const path of base.keys())
364
+ out.push({ path, status: "removed" });
365
+ return out;
366
+ }
367
+ function nextStep(p) {
368
+ if (p.status === "published")
369
+ return "Published: the change is in effect.";
370
+ if (p.status === "closed")
371
+ return "Closed: nothing of it took effect.";
372
+ if (p.readiness.stale) {
373
+ return "A resource changed under it in the same files: write the change again (or close it).";
374
+ }
375
+ if (!p.readiness.valid)
376
+ return "Not valid: see validation.errors and fix the changes.";
377
+ if (p.status === "draft") {
378
+ return "Draft: only its author (and an admin) see it, and nothing changed yet. The person can look at it in the dashboard (Propuestas); open it for review with submit-proposal when they say so.";
379
+ }
380
+ if (p.readiness.ready) {
381
+ return "Open and ready: publish-proposal publishes it \u2014 only once the person confirms.";
382
+ }
383
+ const blocked = p.readiness.blockedBy.length ? ` Changes requested by ${p.readiness.blockedBy.map((b) => b.userName ?? b.userId).join(", ")}.` : "";
384
+ const extra = p.readiness.extraApproval ? ` Written by ${p.authorType === "workflow" ? "a workflow" : "an agent"} (${p.authorName ?? p.authorId}): it needs one approval more than its role requires, and only a person publishes it.` : "";
385
+ const tests = p.readiness.testApproved ? " Its revision is approved for testing: run-proposal-test runs it (it writes for real)." : " Nobody can run it until someone other than its author approves it for testing.";
386
+ return `Open, waiting for review: ${p.readiness.approvals} of ${p.readiness.requiredApprovals} approvals.${blocked}${extra} The members of its role review it in the dashboard; nothing changed yet.${tests}`;
387
+ }
388
+ function summary(p) {
389
+ return {
390
+ id: p.id,
391
+ title: p.title,
392
+ status: p.status,
393
+ role: { id: p.roleId, name: p.roleName },
394
+ author: p.authorName,
395
+ // Who wrote it: a person, or an agent / a workflow on its own (its proposals need one
396
+ // approval more than the role requires).
397
+ authorType: p.authorType ?? "user",
398
+ revision: p.revision,
399
+ resources: p.resources,
400
+ readiness: {
401
+ ready: p.readiness.ready,
402
+ valid: p.readiness.valid,
403
+ stale: p.readiness.stale,
404
+ approvals: p.readiness.approvals,
405
+ requiredApprovals: p.readiness.requiredApprovals,
406
+ blockedBy: p.readiness.blockedBy.map((b) => b.userName ?? b.userId),
407
+ testApproved: p.readiness.testApproved ?? false,
408
+ extraApproval: p.readiness.extraApproval ?? false
409
+ },
410
+ awaitingMyReview: p.awaitingMyReview,
411
+ updatedAt: p.updatedAt
412
+ };
413
+ }
414
+ function proposalReceipt(p) {
415
+ return {
416
+ proposal: {
417
+ ...summary(p),
418
+ description: p.description,
419
+ changes: p.changes.map((c) => ({
420
+ changeId: c.id,
421
+ resourceType: c.resourceType,
422
+ resourceId: c.resourceId,
423
+ resourceName: c.resourceName,
424
+ action: c.action,
425
+ stale: c.stale,
426
+ staleFiles: c.staleFiles,
427
+ files: c.action === "delete" ? [] : changedFiles(c)
428
+ })),
429
+ validation: p.validation,
430
+ publishMode: p.publishMode,
431
+ // Only what can be done from here: reviewing, the bypass and automatic publication are
432
+ // dashboard acts of a person and never appear.
433
+ can: {
434
+ edit: p.permissions.canEdit,
435
+ submit: p.permissions.canSubmit,
436
+ close: p.permissions.canClose,
437
+ comment: p.permissions.canComment,
438
+ publish: p.permissions.canPublish,
439
+ runTests: p.permissions.canRunTests ?? false
440
+ }
441
+ },
442
+ next: nextStep(p)
443
+ };
444
+ }
445
+ var resourceTypeArg = z2.enum([
446
+ "workflow",
447
+ "agent",
448
+ "skill",
449
+ "knowledge-document",
450
+ "role-human-steps"
451
+ ]);
452
+ var fileEditArg = z2.object({
453
+ op: z2.enum(["put", "delete", "replace"]).describe("put = whole file; replace = exact text"),
454
+ path: z2.string().describe("Path inside the tree, e.g. SKILL.md, references/x.md"),
455
+ content: z2.string().optional().describe("put: the whole new content"),
456
+ oldText: z2.string().optional().describe("replace: text that appears exactly once"),
457
+ newText: z2.string().optional().describe("replace: what replaces it")
458
+ }).describe("One edit to one file of the tree");
459
+ var changeArg = z2.object({
460
+ resourceType: resourceTypeArg,
461
+ action: z2.enum(["create", "update", "delete"]),
462
+ resourceId: z2.string().optional().describe("The resource changed or deleted (UUID); absent for a creation"),
463
+ resourceName: z2.string().optional().describe("With edits on a creation: the name of the resource the proposal creates"),
464
+ files: z2.array(z2.object({
465
+ path: z2.string(),
466
+ content: z2.string(),
467
+ encoding: z2.literal("base64").optional()
468
+ })).optional().describe("The WHOLE tree the resource would have (a workflow: workflow.yaml + access.yaml; a skill: SKILL.md + its files; an agent: agent.yaml, AGENT.md and one sub-agents/<name>/ per sub-agent\u2026). A file left out is deleted. Read it from a version (get-workflow-version, or the history) to revert to it."),
469
+ edits: z2.array(fileEditArg).optional().describe("Instead of files: edits applied to the tree the proposal already leaves for the resource (or its current version) \u2014 the other files stay as they are.")
470
+ });
471
+ function changeBody(change) {
472
+ const body = {
473
+ resourceType: change.resourceType,
474
+ action: change.action
475
+ };
476
+ if (change.resourceId !== void 0)
477
+ body.resourceId = change.resourceId;
478
+ if (change.resourceName !== void 0)
479
+ body.resourceName = change.resourceName;
480
+ if (change.files !== void 0)
481
+ body.files = change.files;
482
+ if (change.edits !== void 0)
483
+ body.edits = change.edits.map(fileEditBody);
484
+ return body;
485
+ }
486
+ function fileEditBody(edit) {
487
+ if (edit.op === "put") {
488
+ if (edit.content === void 0)
489
+ throw new Error(`put ${edit.path}: content is required`);
490
+ return { op: "put", path: edit.path, content: edit.content };
491
+ }
492
+ if (edit.op === "delete")
493
+ return { op: "delete", path: edit.path };
494
+ if (edit.oldText === void 0 || edit.newText === void 0) {
495
+ throw new Error(`replace ${edit.path}: oldText and newText are required`);
496
+ }
497
+ return { op: "replace", path: edit.path, oldText: edit.oldText, newText: edit.newText };
498
+ }
499
+ var idArg = z2.string().describe("Proposal ID (UUID)");
500
+ function changeDiff(change, onlyPath) {
501
+ const header = `### ${change.action} ${change.resourceType} ${change.resourceName}` + (change.resourceId ? ` (${change.resourceId}, on version ${change.baseVersion ?? "-"})` : "") + (change.stale ? ` \u2014 STALE in ${change.staleFiles.join(", ") || "the deletion"}` : "");
502
+ if (change.action === "delete")
503
+ return `${header}
504
+ (the whole ${change.resourceType} is deleted)`;
505
+ const base = new Map(change.baseFiles.map((f) => [f.path, f]));
506
+ const after = new Map(change.files.map((f) => [f.path, f]));
507
+ const paths = [.../* @__PURE__ */ new Set([...after.keys(), ...base.keys()])].filter((p) => !onlyPath || p === onlyPath).sort();
508
+ const parts = [header];
509
+ for (const path of paths) {
510
+ const before = base.get(path);
511
+ const now = after.get(path);
512
+ if (before && now && before.content === now.content && before.encoding === now.encoding) {
513
+ continue;
514
+ }
515
+ if (before?.encoding === "base64" || now?.encoding === "base64") {
516
+ parts.push(`--- ${path}
517
+ (binary file ${!before ? "added" : !now ? "removed" : "replaced"})`);
518
+ continue;
519
+ }
520
+ const label = !before ? " (new file)" : !now ? " (deleted)" : "";
521
+ parts.push(`--- a/${path}
522
+ +++ b/${path}${label}
523
+ ${unifiedDiff(before?.content ?? "", now?.content ?? "")}`);
524
+ }
525
+ if (parts.length === 1)
526
+ parts.push("(no file differs from its base)");
527
+ return parts.join("\n");
528
+ }
529
+ var registerProposalTools = (server, client) => {
530
+ server.registerTool("list-proposals", {
531
+ description: "List the proposals you can see (a draft: its author and the admin; an open one: the members of its role). `view`: 'review' = open proposals of your roles awaiting your review (you only review in the dashboard), 'ready' = ready to publish, 'mine' = yours that left draft, 'drafts' = your drafts, 'all' (default). Filter by a resource with resourceType + resourceId.",
532
+ inputSchema: {
533
+ view: z2.enum(["review", "ready", "mine", "drafts", "all"]).optional(),
534
+ status: z2.enum(["draft", "open", "published", "closed"]).optional(),
535
+ resourceType: resourceTypeArg.optional(),
536
+ resourceId: z2.string().optional().describe("Only proposals touching this resource"),
537
+ limit: z2.number().int().min(1).max(200).optional(),
538
+ offset: z2.number().int().min(0).optional()
539
+ },
540
+ annotations: { readOnlyHint: true }
541
+ }, async ({ view, status, resourceType, resourceId, limit, offset }) => {
542
+ const params = {};
543
+ if (view)
544
+ params.view = view;
545
+ if (status)
546
+ params.status = status;
547
+ if (resourceType)
548
+ params.resourceType = resourceType;
549
+ if (resourceId)
550
+ params.resourceId = resourceId;
551
+ if (limit !== void 0)
552
+ params.limit = String(limit);
553
+ if (offset !== void 0)
554
+ params.offset = String(offset);
555
+ const page = await client.get("/api/proposals", params);
556
+ return jsonResult({
557
+ items: page.items.map(summary),
558
+ total: page.total,
559
+ offset: page.offset,
560
+ limit: page.limit
561
+ });
562
+ });
563
+ server.registerTool("get-proposal", {
564
+ description: "A proposal: its changes (which files of which resource, without their content \u2014 get-proposal-diff shows it), validation, where it stands against the publication rules, verdicts, comments and history.",
565
+ inputSchema: { id: idArg },
566
+ annotations: { readOnlyHint: true }
567
+ }, async ({ id }) => {
568
+ const p = await client.get(`/api/proposals/${id}`);
569
+ const receipt = proposalReceipt(p);
570
+ return jsonResult({
571
+ ...receipt,
572
+ proposal: {
573
+ ...receipt.proposal,
574
+ verdicts: p.verdicts.map((v) => ({
575
+ by: v.userName,
576
+ verdict: v.verdict,
577
+ revision: v.revision,
578
+ body: v.body,
579
+ at: v.createdAt
580
+ })),
581
+ comments: p.comments,
582
+ events: p.events.slice(-30)
583
+ }
584
+ });
585
+ });
586
+ server.registerTool("get-proposal-diff", {
587
+ description: "What a proposal changes, as a unified diff per file against the version each change was written on. Narrow it with `resource` (name or id) and `path`.",
588
+ inputSchema: {
589
+ id: idArg,
590
+ resource: z2.string().optional().describe("Only this resource (its name or id)"),
591
+ path: z2.string().optional().describe("Only this file, e.g. SKILL.md")
592
+ },
593
+ annotations: { readOnlyHint: true }
594
+ }, async ({ id, resource, path }) => {
595
+ const p = await client.get(`/api/proposals/${id}`);
596
+ const changes = p.changes.filter((c) => !resource || c.resourceName === resource || c.resourceId === resource);
597
+ const text = `Proposal "${p.title}" (${p.status}, revision ${p.revision})
598
+
599
+ ` + (changes.length ? changes.map((c) => changeDiff(c, path)).join("\n\n") : "(no changes)");
600
+ return { content: [{ type: "text", text }] };
601
+ });
602
+ server.registerTool("create-proposal", {
603
+ description: "Open a new proposal in one of your roles, empty or with changes. Usually the write tools (update-workflow, update-skill, put-skill-file\u2026) are simpler: they take `proposal: {title, description}` and create it. Use this for a change that spans several resources (create it, then pass `proposal: {id}` to each write), or to write whole trees \u2014 e.g. revert an agent or a skill to an earlier version with its files. A document of the role's knowledge is a `knowledge-document` whose tree is one file, `interno/<path>.md` (or `publico/`, `lineamientos/`). The role's human steps (the people's steps of its flow map) are a `role-human-steps` change: action update, resourceId = the role's id, one file `human-steps.yaml` (read it with get-human-steps). It stays a draft (only you and the admin see it) unless draft: false.",
604
+ inputSchema: {
605
+ title: z2.string().describe("What changes, in a line"),
606
+ description: z2.string().describe("Why, for the people who review it"),
607
+ roleId: z2.string().optional().describe("The role it lives in \u2014 required when the person has several roles"),
608
+ draft: z2.boolean().optional().describe("Defaults to true; false opens it for review"),
609
+ changes: z2.array(changeArg).optional()
610
+ },
611
+ annotations: { readOnlyHint: false, destructiveHint: false }
612
+ }, async ({ title, description, roleId, draft, changes }) => {
613
+ const p = await client.post("/api/proposals", {
614
+ title,
615
+ description,
616
+ roleId,
617
+ open: draft === false,
618
+ changes: changes?.map(changeBody)
619
+ });
620
+ return jsonResult(proposalReceipt(p));
621
+ });
622
+ server.registerTool("update-proposal", {
623
+ description: "Change one of your proposals (draft or open): its title or description, add or replace the change of a resource (`changes`, same shape as create-proposal), or drop changes (`removeChangeIds`, from get-proposal). Changing an open proposal makes a new revision: the approvals given on the previous one stop counting.",
624
+ inputSchema: {
625
+ id: idArg,
626
+ title: z2.string().optional(),
627
+ description: z2.string().optional(),
628
+ changes: z2.array(changeArg).optional(),
629
+ removeChangeIds: z2.array(z2.string()).optional()
630
+ },
631
+ annotations: { readOnlyHint: false, destructiveHint: false }
632
+ }, async ({ id, title, description, changes, removeChangeIds }) => {
633
+ let p;
634
+ if (title !== void 0 || description !== void 0) {
635
+ p = await client.patch(`/api/proposals/${id}`, { title, description });
636
+ }
637
+ for (const change of changes ?? []) {
638
+ p = await client.post(`/api/proposals/${id}/changes`, changeBody(change));
639
+ }
640
+ for (const changeId of removeChangeIds ?? []) {
641
+ await client.delete(`/api/proposals/${id}/changes/${changeId}`);
642
+ p = void 0;
643
+ }
644
+ p ??= await client.get(`/api/proposals/${id}`);
645
+ return jsonResult(proposalReceipt(p));
646
+ });
647
+ server.registerTool("submit-proposal", {
648
+ description: "Open one of your drafts for review: the members of its role are told and can see it. Only once the person says so \u2014 a draft is how they look at the change first.",
649
+ inputSchema: { id: idArg },
650
+ annotations: { readOnlyHint: false, destructiveHint: false }
651
+ }, async ({ id }) => {
652
+ const p = await client.post(`/api/proposals/${id}/submit`);
653
+ return jsonResult(proposalReceipt(p));
654
+ });
655
+ server.registerTool("close-proposal", {
656
+ description: "Close a proposal without publishing it (its author, or an admin). Nothing of it takes effect and it cannot be reopened.",
657
+ inputSchema: { id: idArg },
658
+ annotations: { readOnlyHint: false, destructiveHint: true }
659
+ }, async ({ id }) => {
660
+ const p = await client.post(`/api/proposals/${id}/close`);
661
+ return jsonResult(proposalReceipt(p));
662
+ });
663
+ server.registerTool("comment-proposal", {
664
+ description: "Comment on a proposal you can see, while it is a draft or open \u2014 in general, on a file (resourceName + filePath) or on one line of it, or as an answer (parentId, one level). A comment is not a review: approving or requesting changes is done by a person in the dashboard.",
665
+ inputSchema: {
666
+ id: idArg,
667
+ body: z2.string().describe("The comment"),
668
+ resourceType: resourceTypeArg.optional(),
669
+ resourceName: z2.string().optional(),
670
+ filePath: z2.string().optional(),
671
+ line: z2.number().int().positive().optional(),
672
+ parentId: z2.string().optional().describe("The comment this answers")
673
+ },
674
+ annotations: { readOnlyHint: false, destructiveHint: false }
675
+ }, async ({ id, ...comment }) => {
676
+ const p = await client.post(`/api/proposals/${id}/comments`, comment);
677
+ const mine = [...p.comments].sort((a, b) => a.createdAt.localeCompare(b.createdAt)).at(-1);
678
+ return jsonResult({ comment: mine, proposal: summary(p) });
679
+ });
680
+ server.registerTool("run-proposal-test", {
681
+ description: "Run a workflow as an open proposal leaves it: what is published with the proposal on top \u2014 a workflow the proposal creates or changes, or a published workflow of its role that uses an agent or a skill it changes. Possible only once someone other than its author approved the current revision for testing in the dashboard (otherwise PROPOSAL_TEST_FORBIDDEN). It runs with the permissions of the proposal's role and WRITES in the external systems like production \u2014 confirm with the person first. In Dudamel it stays apart: listed only in the proposal, its files and chats deleted when the proposal ends. Pass `trigger` (the inputs) or `rerunOf` (repeat the data of a past run of that workflow). Follow it with get-execution.",
682
+ inputSchema: {
683
+ id: idArg,
684
+ workflow: z2.string().describe("The workflow to run, by name or id"),
685
+ trigger: z2.record(z2.unknown()).optional().describe("Trigger data / inputs, as for a manual run"),
686
+ vars: z2.record(z2.unknown()).optional().describe("Overrides of the workflow vars"),
687
+ rerunOf: z2.string().optional().describe("Execution id whose trigger data to repeat (instead of `trigger`)")
688
+ },
689
+ annotations: { readOnlyHint: false, destructiveHint: true }
690
+ }, async ({ id, ...test }) => {
691
+ const run = await client.post(`/api/proposals/${id}/tests`, test);
692
+ return jsonResult({
693
+ ...run,
694
+ next: run.rejected ? "Not started: a test of this proposal with the same concurrency key is running." : "Started as a test of the proposal: follow it with get-execution(executionId)."
695
+ });
696
+ });
697
+ server.registerTool("publish-proposal", {
698
+ description: "Publish a proposal that ALREADY meets the rules (valid, the approvals its role requires, no pending request for changes): its changes take effect, all or none. Only a member of its role publishes, and only once the person confirms. There is no way to approve or to skip the review from here: a proposal that is not ready answers PROPOSAL_NOT_READY_CONFLICT and waits for its reviewers in the dashboard.",
699
+ inputSchema: { id: idArg },
700
+ annotations: { readOnlyHint: false, destructiveHint: true }
701
+ }, async ({ id }) => {
702
+ const p = await client.post(`/api/proposals/${id}/publish`, {});
703
+ return jsonResult(proposalReceipt(p));
704
+ });
705
+ };
706
+
191
707
  // src/tools/agents.ts
192
708
  import { readFile, stat } from "node:fs/promises";
193
709
  import { extname, resolve } from "node:path";
194
- import { z as z2 } from "zod";
710
+ import { z as z3 } from "zod";
711
+ var REVIEWED = " Nothing changes until its proposal is published: pass `proposal` (see its description); the result is the proposal and what to do next.";
195
712
  function registerAgentTools(server, client, ctx) {
196
713
  server.registerTool(
197
714
  "list-agents",
@@ -209,7 +726,7 @@ function registerAgentTools(server, client, ctx) {
209
726
  {
210
727
  description: "Get detailed information about a specific agent, including prompt sections, system prompt, and config.",
211
728
  inputSchema: {
212
- id: z2.string().describe("Agent ID (UUID)")
729
+ id: z3.string().describe("Agent ID (UUID)")
213
730
  },
214
731
  annotations: { readOnlyHint: true }
215
732
  },
@@ -223,7 +740,7 @@ function registerAgentTools(server, client, ctx) {
223
740
  {
224
741
  description: "List the sub-agents assigned to a specific (parent) agent.",
225
742
  inputSchema: {
226
- id: z2.string().describe("Parent agent ID (UUID)")
743
+ id: z3.string().describe("Parent agent ID (UUID)")
227
744
  },
228
745
  annotations: { readOnlyHint: true }
229
746
  },
@@ -237,8 +754,8 @@ function registerAgentTools(server, client, ctx) {
237
754
  {
238
755
  description: "Download an agent definition (persona + skills) as files in the target tool's on-disk layout (e.g. .claude/agents/<name>.md + .claude/skills/ for Claude Code). Returns {agentName, files: [{path, content, skipIfExists?}]} \u2014 write each file at its path relative to the current working directory; do NOT overwrite existing files marked skipIfExists. Iterate locally, then push changes back with update-agent/update-skill.",
239
756
  inputSchema: {
240
- id: z2.string().describe("Agent ID (UUID)"),
241
- format: z2.enum(["claude-code", "codex", "kimi-code", "opencode", "raw"]).optional().describe(
757
+ id: z3.string().describe("Agent ID (UUID)"),
758
+ format: z3.enum(["claude-code", "codex", "kimi-code", "opencode", "raw"]).optional().describe(
242
759
  "Target tool layout \u2014 defaults to 'claude-code'; 'raw' is a dudamel-native <name>/AGENT.md layout"
243
760
  )
244
761
  },
@@ -252,45 +769,51 @@ function registerAgentTools(server, client, ctx) {
252
769
  server.registerTool(
253
770
  "update-agent",
254
771
  {
255
- description: "Update an agent definition. Requires edit permission on the agent (business-role permission or admin).",
772
+ description: "Propose changes to an agent definition (prompts, model, provider, name\u2026). Requires being a member of its owner role. A sub-agent is changed through its parent: the proposal holds the parent's tree. Only `kind` applies directly (it is not reviewed)." + REVIEWED,
256
773
  inputSchema: {
257
- id: z2.string().describe("Agent ID (UUID)"),
258
- name: z2.string().optional().describe("New name"),
259
- displayName: z2.string().optional().describe("New display name"),
260
- description: z2.string().optional().describe("New description"),
261
- identity: z2.string().optional().describe("New identity"),
262
- instructions: z2.string().optional().describe("New instructions"),
263
- systemPrompt: z2.string().optional().describe("New system prompt"),
264
- model: z2.string().optional().describe("New model identifier"),
265
- skipPermissions: z2.boolean().optional().describe("Skip permission prompts"),
266
- driverProvider: z2.string().optional().describe("New AI provider instance name"),
267
- driverMode: z2.enum(["api", "cli"]).optional().describe("New driver mode"),
268
- kind: z2.enum(["system", "user"]).optional().describe(
774
+ id: z3.string().describe("Agent ID (UUID)"),
775
+ name: z3.string().optional().describe("New name"),
776
+ displayName: z3.string().optional().describe("New display name"),
777
+ description: z3.string().optional().describe("New description"),
778
+ instructions: z3.string().optional().describe(
779
+ "The agent's whole new AGENT.md (it replaces the current one): its criteria, tone and domain. Not its workflows, tools, skills or agents: Dudamel writes those in every turn"
780
+ ),
781
+ model: z3.string().optional().describe("New model identifier"),
782
+ skipPermissions: z3.boolean().optional().describe("Skip permission prompts"),
783
+ driverProvider: z3.string().optional().describe("New AI provider instance name"),
784
+ driverMode: z3.enum(["api", "cli"]).optional().describe("New driver mode"),
785
+ kind: z3.enum(["system", "user"]).optional().describe(
269
786
  "Agent kind \u2014 set to 'user' to convert a disk-seeded 'system' agent into a normal editable user agent"
270
- )
787
+ ),
788
+ proposal: proposalArg
271
789
  },
272
790
  annotations: { readOnlyHint: false, destructiveHint: false }
273
791
  },
274
- async ({ id, ...updates }) => {
275
- const result = await client.put(`/api/agents/${id}`, updates);
276
- return jsonResult(result);
792
+ async ({ id, proposal, ...updates }) => {
793
+ const out = await reviewedWrite(client, "PUT", `/api/agents/${id}`, updates, proposal);
794
+ return reviewedResult(out);
277
795
  }
278
796
  );
279
797
  server.registerTool(
280
798
  "set-agent-sub-agents",
281
799
  {
282
- description: "Set the sub-agent assignments for a (parent) agent. Replaces existing assignments. Each sub-agent id must be an agent created with isSubAgent=true. Requires edit permission on the parent agent.",
800
+ description: "Propose the sub-agent assignments of a (parent) agent. Replaces existing assignments. Each sub-agent id must be an agent created with isSubAgent=true. Requires edit permission on the parent agent." + REVIEWED,
283
801
  inputSchema: {
284
- id: z2.string().describe("Parent agent ID (UUID)"),
285
- subAgentIds: z2.array(z2.string()).describe("Sub-agent IDs (UUIDs) to assign")
802
+ id: z3.string().describe("Parent agent ID (UUID)"),
803
+ subAgentIds: z3.array(z3.string()).describe("Sub-agent IDs (UUIDs) to assign"),
804
+ proposal: proposalArg
286
805
  },
287
806
  annotations: { readOnlyHint: false, destructiveHint: false }
288
807
  },
289
- async ({ id, subAgentIds }) => {
290
- const page = await client.put(`/api/agents/${id}/sub-agents`, {
291
- subAgentIds
292
- });
293
- return jsonResult({ subAgentIds: page.items });
808
+ async ({ id, subAgentIds, proposal }) => {
809
+ const out = await reviewedWrite(
810
+ client,
811
+ "PUT",
812
+ `/api/agents/${id}/sub-agents`,
813
+ { subAgentIds },
814
+ proposal
815
+ );
816
+ return reviewedResult(out, (page) => ({ subAgentIds: page.items }));
294
817
  }
295
818
  );
296
819
  server.registerTool(
@@ -298,7 +821,7 @@ function registerAgentTools(server, client, ctx) {
298
821
  {
299
822
  description: "Activate an agent so it starts receiving and answering messages.",
300
823
  inputSchema: {
301
- id: z2.string().describe("Agent ID (UUID)")
824
+ id: z3.string().describe("Agent ID (UUID)")
302
825
  },
303
826
  annotations: { readOnlyHint: false, destructiveHint: false }
304
827
  },
@@ -312,7 +835,7 @@ function registerAgentTools(server, client, ctx) {
312
835
  {
313
836
  description: "Deactivate an agent \u2014 it stops receiving messages (Slack, dashboard chat) until reactivated. The definition is kept; this is the way to silence an agent without deleting it.",
314
837
  inputSchema: {
315
- id: z2.string().describe("Agent ID (UUID)")
838
+ id: z3.string().describe("Agent ID (UUID)")
316
839
  },
317
840
  annotations: { readOnlyHint: false, destructiveHint: false }
318
841
  },
@@ -324,43 +847,51 @@ function registerAgentTools(server, client, ctx) {
324
847
  server.registerTool(
325
848
  "set-agent-avatar",
326
849
  {
327
- description: "Set an agent's avatar (its picture in the Dashboard, chat and lists) from an image file on disk \u2014 typically one the user attached to the conversation, which you find under `.attachments/` in your workspace. PNG, JPEG, WebP or GIF, under 2 MB. Replaces the current avatar. Needs edit permission on the agent.",
850
+ description: "Set an agent's avatar (its picture in the Dashboard, chat and lists) from an image file on disk \u2014 typically one the user attached to the conversation, which you find under `.attachments/` in your workspace. PNG, JPEG, WebP or GIF, under 2 MB. Replaces the current avatar. Needs edit permission on the agent. The avatar is part of what is reviewed." + REVIEWED,
328
851
  inputSchema: {
329
- id: z2.string().describe("Agent ID (UUID)"),
330
- imagePath: z2.string().describe("Path to the image file, e.g. .attachments/selfie.png (relative to your cwd)")
852
+ id: z3.string().describe("Agent ID (UUID)"),
853
+ imagePath: z3.string().describe("Path to the image file, e.g. .attachments/selfie.png (relative to your cwd)"),
854
+ proposal: proposalArg
331
855
  },
332
856
  annotations: { readOnlyHint: false, destructiveHint: false }
333
857
  },
334
- async ({ id, imagePath }) => {
858
+ async ({ id, imagePath, proposal }) => {
335
859
  const { imageData, mimeType, bytes } = await readAvatarFile(imagePath);
336
- await client.post(`/api/agents/${id}/avatar`, { imageData, mimeType });
337
- return jsonResult({ id, avatar: { mimeType, bytes } });
860
+ const out = await reviewedWrite(
861
+ client,
862
+ "POST",
863
+ `/api/agents/${id}/avatar`,
864
+ { imageData, mimeType },
865
+ proposal
866
+ );
867
+ return reviewedResult(out, () => ({ id, avatar: { mimeType, bytes } }));
338
868
  }
339
869
  );
340
870
  server.registerTool(
341
871
  "create-agent",
342
872
  {
343
- description: "Create a new agent definition. It belongs to one role (its owner role): the members of that role configure it and talk to it with the full profile; anyone else is a guest. If the person has several roles, ask them which one and pass ownerRoleId. A sub-agent (parentAgentId) takes its parent's role instead.",
873
+ description: "Create a new agent definition. It belongs to one role (its owner role): the members of that role configure it and talk to it with the full profile; anyone else is a guest. If the person has several roles, ask them which one and pass ownerRoleId. A sub-agent (parentAgentId) takes its parent's role instead and goes into a proposal on the parent. Creating is proposing: the agent exists once its proposal is published." + REVIEWED,
344
874
  inputSchema: {
345
- name: z2.string().describe("Agent name (unique, kebab-case)"),
346
- displayName: z2.string().optional().describe("Display name shown in the UI"),
347
- description: z2.string().optional().describe("Agent description"),
348
- identity: z2.string().optional().describe('Agent identity (e.g. "senior backend developer")'),
349
- instructions: z2.string().optional().describe("Agent instructions (appended to system prompt)"),
350
- systemPrompt: z2.string().optional().describe("System prompt for the agent"),
351
- model: z2.string().optional().describe('Model identifier (e.g. "claude-sonnet-4-6")'),
352
- skipPermissions: z2.boolean().optional().describe("Skip permission prompts in coding agents"),
353
- driverProvider: z2.string().optional().describe("AI provider instance name for the driver"),
354
- driverMode: z2.enum(["api", "cli"]).optional().describe("Driver mode: api (conversational) or cli (coding)"),
355
- isSubAgent: z2.boolean().optional().describe("Mark as a sub-agent (not shown in top-level lists)"),
356
- ownerRoleId: z2.string().optional().describe("Owner role id \u2014 required when the person has several roles"),
357
- parentAgentId: z2.string().optional().describe("Create it as a sub-agent of this agent (it takes the parent's role)")
875
+ name: z3.string().describe("Agent name (unique, kebab-case)"),
876
+ displayName: z3.string().optional().describe("Display name shown in the UI"),
877
+ description: z3.string().optional().describe("Agent description"),
878
+ instructions: z3.string().optional().describe(
879
+ "The agent's AGENT.md: who it is, its criteria, tone and domain, in markdown. Not its workflows, tools, skills or agents: Dudamel writes those in every turn"
880
+ ),
881
+ model: z3.string().optional().describe('Model identifier (e.g. "claude-sonnet-4-6")'),
882
+ skipPermissions: z3.boolean().optional().describe("Skip permission prompts in coding agents"),
883
+ driverProvider: z3.string().optional().describe("AI provider instance name for the driver"),
884
+ driverMode: z3.enum(["api", "cli"]).optional().describe("Driver mode: api (conversational) or cli (coding)"),
885
+ isSubAgent: z3.boolean().optional().describe("Mark as a sub-agent (not shown in top-level lists)"),
886
+ ownerRoleId: z3.string().optional().describe("Owner role id \u2014 required when the person has several roles"),
887
+ parentAgentId: z3.string().optional().describe("Create it as a sub-agent of this agent (it takes the parent's role)"),
888
+ proposal: proposalArg
358
889
  },
359
890
  annotations: { readOnlyHint: false, destructiveHint: false }
360
891
  },
361
- async ({ name, ...rest }) => {
362
- const result = await client.post("/api/agents", { name, ...rest });
363
- return jsonResult(result);
892
+ async ({ name, proposal, ...rest }) => {
893
+ const out = await reviewedWrite(client, "POST", "/api/agents", { name, ...rest }, proposal);
894
+ return reviewedResult(out);
364
895
  }
365
896
  );
366
897
  if (ctx.role !== "admin") return;
@@ -369,10 +900,10 @@ function registerAgentTools(server, client, ctx) {
369
900
  {
370
901
  description: "Get the agent's recent conversational turns, newest first \u2014 status, duration, model, tokens, the MCP servers the turn brought up, and the failure reason when it failed. This is the way to debug an agent that is not answering: a `failed` turn carries the error code and the CLI stderr tail. Returns metadata only, never the conversation text.",
371
902
  inputSchema: {
372
- id: z2.string().describe("Agent ID (UUID)"),
373
- status: z2.enum(["completed", "failed"]).optional().describe("Only return turns with this outcome"),
374
- limit: z2.number().int().min(1).max(200).optional().describe("Number of turns to return (default: 50)"),
375
- offset: z2.number().int().min(0).optional().describe("Pagination offset")
903
+ id: z3.string().describe("Agent ID (UUID)"),
904
+ status: z3.enum(["completed", "failed"]).optional().describe("Only return turns with this outcome"),
905
+ limit: z3.number().int().min(1).max(200).optional().describe("Number of turns to return (default: 50)"),
906
+ offset: z3.number().int().min(0).optional().describe("Pagination offset")
376
907
  },
377
908
  annotations: { readOnlyHint: true }
378
909
  },
@@ -399,7 +930,7 @@ function registerAgentTools(server, client, ctx) {
399
930
  {
400
931
  description: "Get token usage statistics per agent over a time window. Useful for monitoring costs.",
401
932
  inputSchema: {
402
- windowHours: z2.number().int().min(1).optional().describe("Time window in hours (default: 24)")
933
+ windowHours: z3.number().int().min(1).optional().describe("Time window in hours (default: 24)")
403
934
  },
404
935
  annotations: { readOnlyHint: true }
405
936
  },
@@ -439,7 +970,7 @@ async function readAvatarFile(imagePath) {
439
970
  }
440
971
 
441
972
  // src/tools/skills.ts
442
- import { z as z3 } from "zod";
973
+ import { z as z4 } from "zod";
443
974
 
444
975
  // src/skill-bundle.ts
445
976
  import { createHash } from "node:crypto";
@@ -618,6 +1149,19 @@ function writeReceipt(skill) {
618
1149
  files: digestFiles(skill.files ?? [])
619
1150
  };
620
1151
  }
1152
+ function skillWriteResult(out, skill) {
1153
+ if (out.kind === "direct") return jsonResult(writeReceipt(out.result));
1154
+ return jsonResult(proposedSkillReceipt(out.proposal, skill));
1155
+ }
1156
+ function proposedSkillReceipt(p, skill) {
1157
+ const change = p.changes.find(
1158
+ (c) => c.resourceType === "skill" && (skill.id !== void 0 && c.resourceId === skill.id || skill.id === void 0 && c.resourceName === skill.name)
1159
+ );
1160
+ return {
1161
+ ...proposalReceipt(p),
1162
+ skillInProposal: change ? { name: change.resourceName, action: change.action, files: digestFiles(change.files) } : null
1163
+ };
1164
+ }
621
1165
  async function resolveBundle(args) {
622
1166
  if (args.skillDir === void 0) return { content: args.content, files: args.files };
623
1167
  if (args.content !== void 0 || args.files !== void 0) {
@@ -635,8 +1179,8 @@ function registerSkillTools(server, client, ctx) {
635
1179
  {
636
1180
  description: "List skill definitions (active by default). Metadata only \u2014 id, name, description, status, origin, version, file count and timestamps. Use get-skill or download-skill to read a specific skill.",
637
1181
  inputSchema: {
638
- status: z3.enum(["active", "archived"]).optional().describe("Lifecycle filter \u2014 defaults to 'active'; pass 'archived' for archived skills"),
639
- query: z3.string().optional().describe("Case-insensitive substring match against the name and description")
1182
+ status: z4.enum(["active", "archived"]).optional().describe("Lifecycle filter \u2014 defaults to 'active'; pass 'archived' for archived skills"),
1183
+ query: z4.string().optional().describe("Case-insensitive substring match against the name and description")
640
1184
  },
641
1185
  annotations: { readOnlyHint: true }
642
1186
  },
@@ -655,8 +1199,8 @@ function registerSkillTools(server, client, ctx) {
655
1199
  {
656
1200
  description: "Get detailed information about a specific skill, including content, allowed tools, files, and version info. For a large skill prefer download-skill with outDir, which puts the files on disk instead of in the conversation.",
657
1201
  inputSchema: {
658
- id: z3.string().describe("Skill ID (UUID)"),
659
- includeContent: z3.boolean().optional().describe(
1202
+ id: z4.string().describe("Skill ID (UUID)"),
1203
+ includeContent: z4.boolean().optional().describe(
660
1204
  "Defaults to true. With false, returns metadata plus a size and sha256 per file \u2014 enough to check what is stored without pulling the content in."
661
1205
  )
662
1206
  },
@@ -681,7 +1225,7 @@ function registerSkillTools(server, client, ctx) {
681
1225
  {
682
1226
  description: "List version history for a skill. Returns version numbers, change summaries, and creation dates.",
683
1227
  inputSchema: {
684
- id: z3.string().describe("Skill ID (UUID)")
1228
+ id: z4.string().describe("Skill ID (UUID)")
685
1229
  },
686
1230
  annotations: { readOnlyHint: true }
687
1231
  },
@@ -695,14 +1239,14 @@ function registerSkillTools(server, client, ctx) {
695
1239
  {
696
1240
  description: "Download a skill as files in the target tool's on-disk layout (e.g. .claude/skills/<name>/SKILL.md for Claude Code). With `outDir` the files are written to disk and only their paths, sizes and hashes come back \u2014 the way to handle a skill of any size. Without it, the content is returned inline. Then edit the folder and push it back with update-skill + skillDir.",
697
1241
  inputSchema: {
698
- id: z3.string().describe("Skill ID (UUID)"),
699
- format: z3.enum(["claude-code", "codex", "kimi-code", "opencode", "raw"]).optional().describe(
1242
+ id: z4.string().describe("Skill ID (UUID)"),
1243
+ format: z4.enum(["claude-code", "codex", "kimi-code", "opencode", "raw"]).optional().describe(
700
1244
  "Target tool layout \u2014 defaults to 'claude-code'; 'raw' is the dudamel-native <name>/SKILL.md layout"
701
1245
  ),
702
- outDir: z3.string().optional().describe(
1246
+ outDir: z4.string().optional().describe(
703
1247
  "Directory to write the files into (created if missing). Paths from the chosen format are kept, so outDir is the root the layout hangs from."
704
1248
  ),
705
- overwrite: z3.boolean().optional().describe(
1249
+ overwrite: z4.boolean().optional().describe(
706
1250
  "Defaults to false: if a file already exists with different content the call is rejected and nothing is written, so a re-download cannot erase edits in flight."
707
1251
  )
708
1252
  },
@@ -724,7 +1268,7 @@ function registerSkillTools(server, client, ctx) {
724
1268
  {
725
1269
  description: "Get the skill definitions assigned to a specific agent.",
726
1270
  inputSchema: {
727
- agentId: z3.string().describe("Agent ID (UUID)")
1271
+ agentId: z4.string().describe("Agent ID (UUID)")
728
1272
  },
729
1273
  annotations: { readOnlyHint: true }
730
1274
  },
@@ -737,28 +1281,29 @@ function registerSkillTools(server, client, ctx) {
737
1281
  server.registerTool(
738
1282
  "create-skill",
739
1283
  {
740
- description: "Create a new skill definition. It belongs to one role (its owner role): the members of that role edit it and assign it to the role's agents; another role that needs it makes its own copy. Pass `skillDir` to upload a directory from disk instead of inlining every file. Returns the new version plus a size and sha256 per stored file. " + FILES_SEMANTICS,
1284
+ description: "Create a new skill definition. It belongs to one role (its owner role): the members of that role edit it and assign it to the role's agents; another role that needs it makes its own copy. Pass `skillDir` to upload a directory from disk instead of inlining every file. Creating is proposing: the skill exists once its proposal is published; the result carries a size and sha256 per file of what the proposal holds. " + FILES_SEMANTICS + REVIEWED,
741
1285
  inputSchema: {
742
- name: z3.string().describe("Skill name (unique within the role, kebab-case)"),
743
- content: z3.string().optional().describe(
1286
+ name: z4.string().describe("Skill name (unique within the role, kebab-case)"),
1287
+ content: z4.string().optional().describe(
744
1288
  "Skill content \u2014 the full SKILL.md is fine: its frontmatter (description, version, allowed-tools, model) is honored, and an argument passed explicitly here wins over it. Required unless skillDir is given."
745
1289
  ),
746
- skillDir: z3.string().optional().describe(SKILL_DIR_HELP),
747
- description: z3.string().optional().describe("Skill description"),
748
- disableModelInvocation: z3.boolean().optional().describe("Disable model-triggered invocation"),
749
- userInvocable: z3.boolean().optional().describe("Allow user to invoke via slash command"),
750
- model: z3.string().optional().describe("Model identifier or tier"),
751
- allowedTools: z3.array(z3.string()).optional().describe("List of allowed tool names"),
752
- currentVersion: z3.string().optional().describe("Initial version string"),
753
- files: z3.array(
754
- z3.object({
755
- path: z3.string().describe("Relative file path within the skill"),
756
- content: z3.string().describe("File content")
1290
+ skillDir: z4.string().optional().describe(SKILL_DIR_HELP),
1291
+ description: z4.string().optional().describe("Skill description"),
1292
+ disableModelInvocation: z4.boolean().optional().describe("Disable model-triggered invocation"),
1293
+ userInvocable: z4.boolean().optional().describe("Allow user to invoke via slash command"),
1294
+ model: z4.string().optional().describe("Model identifier or tier"),
1295
+ allowedTools: z4.array(z4.string()).optional().describe("List of allowed tool names"),
1296
+ currentVersion: z4.string().optional().describe("Initial version string"),
1297
+ files: z4.array(
1298
+ z4.object({
1299
+ path: z4.string().describe("Relative file path within the skill"),
1300
+ content: z4.string().describe("File content")
757
1301
  })
758
1302
  ).optional().describe(`Embedded skill files. ${FILES_SEMANTICS}`),
759
- ownerRoleId: z3.string().optional().describe(
1303
+ ownerRoleId: z4.string().optional().describe(
760
1304
  "Role the skill belongs to (its agents are that role's) \u2014 required when the person has several roles. A name is unique per role."
761
- )
1305
+ ),
1306
+ proposal: proposalArg
762
1307
  },
763
1308
  annotations: { readOnlyHint: false, destructiveHint: false }
764
1309
  },
@@ -773,68 +1318,78 @@ function registerSkillTools(server, client, ctx) {
773
1318
  allowedTools,
774
1319
  currentVersion,
775
1320
  files,
776
- ownerRoleId
1321
+ ownerRoleId,
1322
+ proposal
777
1323
  }) => {
778
1324
  const bundle = await resolveBundle({ content, files, skillDir });
779
1325
  if (bundle.content === void 0) {
780
1326
  throw new Error("A new skill needs either content or skillDir.");
781
1327
  }
782
- const result = await client.post("/api/skills", {
783
- name,
784
- content: bundle.content,
785
- description,
786
- disableModelInvocation,
787
- userInvocable,
788
- model,
789
- allowedTools,
790
- currentVersion,
791
- files: bundle.files,
792
- ownerRoleId
793
- });
794
- return jsonResult(writeReceipt(result));
1328
+ const out = await reviewedWrite(
1329
+ client,
1330
+ "POST",
1331
+ "/api/skills",
1332
+ {
1333
+ name,
1334
+ content: bundle.content,
1335
+ description,
1336
+ disableModelInvocation,
1337
+ userInvocable,
1338
+ model,
1339
+ allowedTools,
1340
+ currentVersion,
1341
+ files: bundle.files,
1342
+ ownerRoleId
1343
+ },
1344
+ proposal
1345
+ );
1346
+ return skillWriteResult(out, { name });
795
1347
  }
796
1348
  );
797
1349
  server.registerTool(
798
1350
  "update-skill",
799
1351
  {
800
- description: "Update a skill definition. Creates a new version entry. Pass `skillDir` to upload an edited directory from disk in one call instead of retyping every file. Returns the new version plus a size and sha256 per stored file, so the upload can be verified without downloading it back. " + FILES_SEMANTICS,
1352
+ description: "Propose an update of a skill definition; once published it is a new version. Pass `skillDir` to upload an edited directory from disk in one call instead of retyping every file. To change ONE file, put-skill-file / edit-skill-file / delete-skill-file are cheaper. Returns a size and sha256 per file of what the proposal holds, so the upload can be verified without downloading it back. " + FILES_SEMANTICS + REVIEWED,
801
1353
  inputSchema: {
802
- id: z3.string().describe("Skill ID (UUID)"),
803
- name: z3.string().optional().describe(
1354
+ id: z4.string().describe("Skill ID (UUID)"),
1355
+ name: z4.string().optional().describe(
804
1356
  "New skill name (unique, kebab-case) \u2014 rename the skill; agent assignments are by id and survive the rename"
805
1357
  ),
806
- content: z3.string().optional().describe(
1358
+ content: z4.string().optional().describe(
807
1359
  "New skill content \u2014 the full SKILL.md is fine: its frontmatter (description, version, allowed-tools, model) is honored, and an argument passed explicitly here wins over it."
808
1360
  ),
809
- skillDir: z3.string().optional().describe(SKILL_DIR_HELP),
810
- description: z3.string().optional().describe("New description"),
811
- disableModelInvocation: z3.boolean().optional().describe("Disable model-triggered invocation"),
812
- userInvocable: z3.boolean().optional().describe("Allow user to invoke via slash command"),
813
- model: z3.string().optional().describe("Model identifier or tier"),
814
- allowedTools: z3.array(z3.string()).optional().describe("List of allowed tool names"),
815
- currentVersion: z3.string().optional().describe("Version string for this update"),
816
- changeSummary: z3.string().optional().describe("Summary of what changed in this version"),
817
- files: z3.array(
818
- z3.object({
819
- path: z3.string().describe("Relative file path within the skill"),
820
- content: z3.string().describe("File content")
1361
+ skillDir: z4.string().optional().describe(SKILL_DIR_HELP),
1362
+ description: z4.string().optional().describe("New description"),
1363
+ disableModelInvocation: z4.boolean().optional().describe("Disable model-triggered invocation"),
1364
+ userInvocable: z4.boolean().optional().describe("Allow user to invoke via slash command"),
1365
+ model: z4.string().optional().describe("Model identifier or tier"),
1366
+ allowedTools: z4.array(z4.string()).optional().describe("List of allowed tool names"),
1367
+ currentVersion: z4.string().optional().describe("Version string for this update"),
1368
+ changeSummary: z4.string().optional().describe("Summary of what changed in this version"),
1369
+ files: z4.array(
1370
+ z4.object({
1371
+ path: z4.string().describe("Relative file path within the skill"),
1372
+ content: z4.string().describe("File content")
821
1373
  })
822
- ).optional().describe(`Embedded skill files. ${FILES_SEMANTICS}`)
1374
+ ).optional().describe(`Embedded skill files. ${FILES_SEMANTICS}`),
1375
+ proposal: proposalArg
823
1376
  },
824
1377
  annotations: { readOnlyHint: false, destructiveHint: false }
825
1378
  },
826
- async ({ id, skillDir, ...updates }) => {
1379
+ async ({ id, skillDir, proposal, ...updates }) => {
827
1380
  const bundle = await resolveBundle({
828
1381
  content: updates.content,
829
1382
  files: updates.files,
830
1383
  skillDir
831
1384
  });
832
- const result = await client.put(`/api/skills/${id}`, {
833
- ...updates,
834
- content: bundle.content,
835
- files: bundle.files
836
- });
837
- return jsonResult(writeReceipt(result));
1385
+ const out = await reviewedWrite(
1386
+ client,
1387
+ "PUT",
1388
+ `/api/skills/${id}`,
1389
+ { ...updates, content: bundle.content, files: bundle.files },
1390
+ proposal
1391
+ );
1392
+ return skillWriteResult(out, { id });
838
1393
  }
839
1394
  );
840
1395
  server.registerTool(
@@ -842,7 +1397,7 @@ function registerSkillTools(server, client, ctx) {
842
1397
  {
843
1398
  description: "Archive a skill (logical delete \u2014 versions and files are kept; it disappears from default listings and cannot be assigned). Fails with SKILL_IN_USE while assigned to agents: unassign it first.",
844
1399
  inputSchema: {
845
- id: z3.string().describe("Skill ID (UUID)")
1400
+ id: z4.string().describe("Skill ID (UUID)")
846
1401
  },
847
1402
  annotations: { readOnlyHint: false, destructiveHint: false }
848
1403
  },
@@ -856,7 +1411,7 @@ function registerSkillTools(server, client, ctx) {
856
1411
  {
857
1412
  description: "Restore an archived skill to active, making it assignable again.",
858
1413
  inputSchema: {
859
- id: z3.string().describe("Skill ID (UUID)")
1414
+ id: z4.string().describe("Skill ID (UUID)")
860
1415
  },
861
1416
  annotations: { readOnlyHint: false, destructiveHint: false }
862
1417
  },
@@ -868,35 +1423,124 @@ function registerSkillTools(server, client, ctx) {
868
1423
  server.registerTool(
869
1424
  "set-agent-skills",
870
1425
  {
871
- description: "Set the skill assignments for an agent. Replaces existing assignments.",
1426
+ description: "Propose the skill assignments of an agent. Replaces existing assignments." + REVIEWED,
872
1427
  inputSchema: {
873
- agentId: z3.string().describe("Agent ID (UUID)"),
874
- skills: z3.array(
875
- z3.object({
876
- skillName: z3.string().describe("Skill name to assign")
1428
+ agentId: z4.string().describe("Agent ID (UUID)"),
1429
+ skills: z4.array(
1430
+ z4.object({
1431
+ skillName: z4.string().describe("Skill name to assign")
877
1432
  })
878
- ).describe("List of skills to assign")
1433
+ ).describe("List of skills to assign"),
1434
+ proposal: proposalArg
879
1435
  },
880
1436
  annotations: { readOnlyHint: false, destructiveHint: false }
881
1437
  },
882
- async ({ agentId, skills }) => {
883
- const page = await client.put(`/api/agents/${agentId}/skills`, {
884
- skills
885
- });
886
- return jsonResult({ skills: page.items });
1438
+ async ({ agentId, skills, proposal }) => {
1439
+ const out = await reviewedWrite(
1440
+ client,
1441
+ "PUT",
1442
+ `/api/agents/${agentId}/skills`,
1443
+ { skills },
1444
+ proposal
1445
+ );
1446
+ if (out.kind === "direct") return jsonResult({ skills: out.result.items });
1447
+ return jsonResult(proposalReceipt(out.proposal));
1448
+ }
1449
+ );
1450
+ registerSkillFileTools(server, client);
1451
+ }
1452
+ var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
1453
+ var SKILL_REF_HELP = "The skill: its ID (UUID), or \u2014 for a skill this same proposal creates \u2014 its name.";
1454
+ var FILE_PATH_HELP = "Path inside the skill: SKILL.md (its frontmatter + body, as get-proposal-diff shows it) or any other file, e.g. references/api.md";
1455
+ async function editSkill(client, skill, edits, arg) {
1456
+ const target = toProposalTarget(arg);
1457
+ if (!target) {
1458
+ throw new Error(
1459
+ "This tool writes into a proposal: pass proposal {title, description} for a new one, or {id} for one of yours."
1460
+ );
1461
+ }
1462
+ const existing = UUID_RE.test(skill);
1463
+ const change = existing ? { resourceType: "skill", action: "update", resourceId: skill, edits } : { resourceType: "skill", action: "create", resourceName: skill, edits };
1464
+ let proposal;
1465
+ if ("id" in target) {
1466
+ proposal = await client.post(`/api/proposals/${target.id}/changes`, change);
1467
+ } else {
1468
+ if (!existing) {
1469
+ throw new Error("A skill a proposal creates is edited inside that proposal: pass proposal {id}.");
1470
+ }
1471
+ const { ownerRoleId } = await client.get(
1472
+ `/api/skills/${skill}`
1473
+ );
1474
+ if (!ownerRoleId) {
1475
+ throw new Error(
1476
+ "This is a system skill: it has no role, takes no proposals and nobody edits it."
1477
+ );
887
1478
  }
1479
+ proposal = await client.post("/api/proposals", {
1480
+ roleId: ownerRoleId,
1481
+ title: target.title,
1482
+ description: target.description,
1483
+ open: !target.draft,
1484
+ changes: [change]
1485
+ });
1486
+ }
1487
+ return jsonResult(proposedSkillReceipt(proposal, existing ? { id: skill } : { name: skill }));
1488
+ }
1489
+ function registerSkillFileTools(server, client) {
1490
+ const common = " Only the file named changes; the rest of the skill stays as it is." + REVIEWED;
1491
+ server.registerTool(
1492
+ "put-skill-file",
1493
+ {
1494
+ description: "Write one whole file of a skill \u2014 create it or replace it \u2014 inside a proposal." + common,
1495
+ inputSchema: {
1496
+ skill: z4.string().describe(SKILL_REF_HELP),
1497
+ path: z4.string().describe(FILE_PATH_HELP),
1498
+ content: z4.string().describe("The whole content of the file"),
1499
+ proposal: proposalArg
1500
+ },
1501
+ annotations: { readOnlyHint: false, destructiveHint: false }
1502
+ },
1503
+ async ({ skill, path, content, proposal }) => editSkill(client, skill, [{ op: "put", path, content }], proposal)
1504
+ );
1505
+ server.registerTool(
1506
+ "edit-skill-file",
1507
+ {
1508
+ description: "Replace a text of one file of a skill by another, inside a proposal. `oldText` must appear EXACTLY ONCE in the file as the proposal leaves it (read it with get-proposal-diff or get-skill): if it does not appear, or appears more than once, nothing changes (PROPOSAL_FILE_EDIT_CONFLICT says how many times) \u2014 include more surrounding text and retry." + common,
1509
+ inputSchema: {
1510
+ skill: z4.string().describe(SKILL_REF_HELP),
1511
+ path: z4.string().describe(FILE_PATH_HELP),
1512
+ oldText: z4.string().describe("The exact text to replace (appears once)"),
1513
+ newText: z4.string().describe("What replaces it (empty deletes the text)"),
1514
+ proposal: proposalArg
1515
+ },
1516
+ annotations: { readOnlyHint: false, destructiveHint: false }
1517
+ },
1518
+ async ({ skill, path, oldText, newText, proposal }) => editSkill(client, skill, [{ op: "replace", path, oldText, newText }], proposal)
1519
+ );
1520
+ server.registerTool(
1521
+ "delete-skill-file",
1522
+ {
1523
+ description: "Delete one file of a skill, inside a proposal. SKILL.md cannot be deleted (delete the skill instead)." + common,
1524
+ inputSchema: {
1525
+ skill: z4.string().describe(SKILL_REF_HELP),
1526
+ path: z4.string().describe(FILE_PATH_HELP),
1527
+ proposal: proposalArg
1528
+ },
1529
+ annotations: { readOnlyHint: false, destructiveHint: true }
1530
+ },
1531
+ async ({ skill, path, proposal }) => editSkill(client, skill, [{ op: "delete", path }], proposal)
888
1532
  );
889
1533
  }
890
1534
 
891
1535
  // src/tools/agent-mcp.ts
892
- import { z as z4 } from "zod";
1536
+ import { z as z5 } from "zod";
893
1537
  function registerAgentMcpTools(server, client, ctx) {
894
1538
  server.registerTool(
895
1539
  "get-agent-mcp-servers",
896
1540
  {
897
1541
  description: "List MCP servers assigned to a specific agent, each with its `mode` (what the owner role gets) and its `guestMode` (what anyone else talking to the agent gets; null = not in the guest profile).",
898
1542
  inputSchema: {
899
- agentId: z4.string().describe("Agent ID (UUID)")
1543
+ agentId: z5.string().describe("Agent ID (UUID)")
900
1544
  },
901
1545
  annotations: { readOnlyHint: true }
902
1546
  },
@@ -909,26 +1553,29 @@ function registerAgentMcpTools(server, client, ctx) {
909
1553
  server.registerTool(
910
1554
  "set-agent-mcp-servers",
911
1555
  {
912
- description: "Set the MCP server assignments for an agent. Replaces existing assignments. Optionally set per-server access mode via `modes` (keyed by MCP server id); ids omitted from `modes` default to 'write' (read-write). `guestModes` is the guest profile \u2014 what someone outside the agent's owner role gets on each server: omit it to leave the guest profile as it is (a newly assigned server starts out of it); pass it and the ids it omits leave the guest profile. A server whose integration the owner role does not use is refused (INTEGRATION_NOT_GRANTED); list-mcp-servers with ownerRoleId says which ones it may have.",
1556
+ description: "Propose the MCP server assignments of an agent. Replaces existing assignments. Optionally set per-server access mode via `modes` (keyed by MCP server id); ids omitted from `modes` default to 'write' (read-write). `guestModes` is the guest profile \u2014 what someone outside the agent's owner role gets on each server: omit it to leave the guest profile as it is (a newly assigned server starts out of it); pass it and the ids it omits leave the guest profile. A server whose integration the owner role does not use is refused (INTEGRATION_NOT_GRANTED); list-mcp-servers with ownerRoleId says which ones it may have." + REVIEWED,
913
1557
  inputSchema: {
914
- agentId: z4.string().describe("Agent ID (UUID)"),
915
- mcpServerIds: z4.array(z4.string()).describe("List of MCP Server IDs (UUIDs) to assign"),
916
- modes: z4.record(z4.enum(["read", "write"])).optional().describe(
1558
+ agentId: z5.string().describe("Agent ID (UUID)"),
1559
+ mcpServerIds: z5.array(z5.string()).describe("List of MCP Server IDs (UUIDs) to assign"),
1560
+ modes: z5.record(z5.enum(["read", "write"])).optional().describe(
917
1561
  "Per-server access mode keyed by MCP server id: 'read' (read-only tools) or 'write' (all tools). Omitted ids default to 'write'."
918
1562
  ),
919
- guestModes: z4.record(z4.enum(["read", "write"])).optional().describe(
1563
+ guestModes: z5.record(z5.enum(["read", "write"])).optional().describe(
920
1564
  "Guest profile keyed by MCP server id, same values as `modes`. Absent = unchanged; present = only these ids are offered to guests."
921
- )
1565
+ ),
1566
+ proposal: proposalArg
922
1567
  },
923
1568
  annotations: { readOnlyHint: false, destructiveHint: false }
924
1569
  },
925
- async ({ agentId, mcpServerIds, modes, guestModes }) => {
926
- const page = await client.put(`/api/agents/${agentId}/mcp-servers`, {
927
- mcpServerIds,
928
- modes,
929
- guestModes
930
- });
931
- return jsonResult({ mcpServerIds: page.items });
1570
+ async ({ agentId, mcpServerIds, modes, guestModes, proposal }) => {
1571
+ const out = await reviewedWrite(
1572
+ client,
1573
+ "PUT",
1574
+ `/api/agents/${agentId}/mcp-servers`,
1575
+ { mcpServerIds, modes, guestModes },
1576
+ proposal
1577
+ );
1578
+ return reviewedResult(out, (page) => ({ mcpServerIds: page.items }));
932
1579
  }
933
1580
  );
934
1581
  }
@@ -937,12 +1584,13 @@ function registerAgentMcpTools(server, client, ctx) {
937
1584
  function createServer(config) {
938
1585
  return createSurfaceServer({
939
1586
  name: "dudamel-agents",
940
- instructions: `Dudamel Agents MCP \u2014 manage agents, skills, and their skill/MCP/sub-agent assignments. Running as role=${config.role}, readOnly=${config.readOnly ?? false}.`,
1587
+ instructions: `Dudamel Agents MCP \u2014 manage agents, skills, and their skill/MCP/sub-agent assignments. An agent or skill of a role changes only through a published proposal: the write tools take \`proposal\` and the *-proposal tools follow it through. Running as role=${config.role}, readOnly=${config.readOnly ?? false}.`,
941
1588
  registrars: [
942
1589
  registerAgentTools,
943
1590
  registerSkillTools,
944
1591
  registerAgentMcpTools,
945
- registerOwnerTools(["agent", "skill"])
1592
+ registerOwnerTools(["agent", "skill"]),
1593
+ registerProposalTools
946
1594
  ],
947
1595
  config
948
1596
  });