@bendyline/gezel-mcp 1.2.8 → 1.2.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/harness.js +2032 -61
  2. package/dist/server.js +319 -230
  3. package/package.json +4 -4
package/dist/harness.js CHANGED
@@ -8,20 +8,1656 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
8
8
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
9
9
  import { RootsListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
10
10
 
11
- // src/harness/issues.ts
12
- import { join as join3 } from "path";
11
+ // src/harness/arguments.ts
12
+ import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
13
+ import { z } from "zod";
14
+ var EXAMPLES = {
15
+ search: { query: "where uploaded files are checked for size" },
16
+ search_memory: { query: "how we name release branches" },
17
+ save_memory: { text: "Releases ship on Tuesdays after the 14:00 check-in." },
18
+ read_doc_as_markdown: { path: "docs/report.docx" },
19
+ read_document: { path: "style-guide.md" },
20
+ describe_image: { path: "screenshots/error.png" },
21
+ generate_image: {
22
+ prompt: "A white delivery van on a quiet street at sunrise, flat illustration"
23
+ },
24
+ convert_document: {
25
+ source: { kind: "markdown", markdown: "# Title\n\nBody text." },
26
+ targets: ["docx"]
27
+ },
28
+ save_artifact: {
29
+ artifactUri: "docblocks://artifacts/<id from convert_document>",
30
+ destination: { path: "report.docx" }
31
+ },
32
+ preview_document: { source: { kind: "artifact", uri: "docblocks://artifacts/<id>" } },
33
+ inspect_document: { source: { kind: "file", path: "docs/report.docx" } }
34
+ };
35
+ function missingArguments(schema, args) {
36
+ const given = args && typeof args === "object" ? args : {};
37
+ return (schema.required ?? []).filter(
38
+ (name) => given[name] === void 0 || given[name] === null
39
+ );
40
+ }
41
+ function describe(schema, name) {
42
+ const description = schema.properties?.[name]?.description?.trim();
43
+ return description ? `\`${name}\` (${description.replace(/\.$/, "")})` : `\`${name}\``;
44
+ }
45
+ function listed(items) {
46
+ return items.length <= 1 ? items[0] ?? "" : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
47
+ }
48
+ function argumentHelp(tool, schema, args, detail) {
49
+ const missing = missingArguments(schema, args);
50
+ const example = EXAMPLES[tool];
51
+ const parts = missing.length > 0 ? [`\`${tool}\` needs ${listed(missing.map((name) => describe(schema, name)))}.`] : [
52
+ `\`${tool}\` could not use those arguments: ${detail ?? "they do not match its schema"}.`,
53
+ ...(schema.required ?? []).length > 0 ? [`It needs ${listed((schema.required ?? []).map((name) => describe(schema, name)))}.`] : []
54
+ ];
55
+ if (example) parts.push(`For example: ${JSON.stringify(example)}`);
56
+ return parts.join(" ");
57
+ }
58
+ var SDK_PREFIX = /^(MCP error -?\d+: )?Input validation error: Invalid arguments for tool \S+: /;
59
+ function teachInvalidArguments(server) {
60
+ const target = server;
61
+ const validate = target.validateToolInput.bind(server);
62
+ target.validateToolInput = async (tool, args, name) => {
63
+ try {
64
+ return await validate(tool, args, name);
65
+ } catch (err) {
66
+ if (!(err instanceof McpError) || err.code !== ErrorCode.InvalidParams) throw err;
67
+ let schema = {};
68
+ try {
69
+ schema = z.toJSONSchema(tool.inputSchema, { io: "input" });
70
+ } catch {
71
+ }
72
+ throw new Error(argumentHelp(name, schema, args, err.message.replace(SDK_PREFIX, "")));
73
+ }
74
+ };
75
+ }
76
+
77
+ // src/harness/documents.ts
78
+ import { createHash } from "crypto";
79
+ import { constants, existsSync, readFileSync as readFileSync2 } from "fs";
80
+ import { access, mkdir } from "fs/promises";
81
+ import { tmpdir } from "os";
82
+ import { basename, dirname, isAbsolute as isAbsolute4, join as join3, resolve as resolve3 } from "path";
13
83
  import {
14
- HARNESS_PROMPTS,
15
- HARNESS_PROMPT_NAMES,
16
- HARNESS_TOOL_DESCRIPTIONS as HARNESS_TOOL_DESCRIPTIONS2,
17
- ISSUE_VERDICT_KINDS,
18
- MAX_APP_ISSUE_VERDICTS_PER_CALL,
19
- harnessPromptCount,
20
- renderEmptyIssuePrompt,
21
- renderHarnessIssuePrompt,
22
- renderIssueBatch
84
+ HARNESS_DOCUMENT_TOOL_NAMES,
85
+ HARNESS_DOCUMENT_TOOL_NOTES
23
86
  } from "@bendyline/gezel";
24
- import { z as z2 } from "zod";
87
+ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
88
+ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
89
+ import { z as z3 } from "zod";
90
+
91
+ // src/harness/docblocks-tools.json
92
+ var docblocks_tools_default = {
93
+ docblocksVersion: "2.7.5",
94
+ tools: [
95
+ {
96
+ name: "convert_document",
97
+ description: "Convert plain text, Markdown, bundles, or linked-registry inputs directly into one or more immutable artifacts. Plain Markdown needs no preflight or annotations; valid Squisq annotations are optional layout hints. For PPTX, heading-based slide boundaries do not need --- separators. Use save_artifact only for durable filesystem output.",
98
+ inputSchema: {
99
+ type: "object",
100
+ properties: {
101
+ source: {
102
+ anyOf: [
103
+ {
104
+ type: "object",
105
+ properties: {
106
+ kind: {
107
+ type: "string",
108
+ const: "markdown"
109
+ },
110
+ markdown: {
111
+ type: "string",
112
+ maxLength: 20971520,
113
+ pattern: "^[^\\u0000\\u007f]*$"
114
+ },
115
+ name: {
116
+ anyOf: [
117
+ {
118
+ type: "string",
119
+ maxLength: 1024,
120
+ pattern: "^[^\\u0000\\u007f]*$"
121
+ },
122
+ {
123
+ type: "null"
124
+ }
125
+ ],
126
+ default: null
127
+ }
128
+ },
129
+ required: ["kind", "markdown"],
130
+ additionalProperties: false
131
+ },
132
+ {
133
+ type: "object",
134
+ properties: {
135
+ kind: {
136
+ type: "string",
137
+ const: "file"
138
+ },
139
+ rootId: {
140
+ anyOf: [
141
+ {
142
+ type: "string",
143
+ minLength: 1,
144
+ maxLength: 256,
145
+ pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
146
+ },
147
+ {
148
+ type: "null"
149
+ }
150
+ ],
151
+ default: null
152
+ },
153
+ path: {
154
+ type: "string",
155
+ minLength: 1,
156
+ maxLength: 4096,
157
+ pattern: "^(?!\\/)(?![A-Za-z]:)(?!.*(?:^|\\/)(?:\\.{1,2})(?:\\/|$))(?!.*\\/\\/)(?!.*[\\\\\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"
158
+ },
159
+ format: {
160
+ anyOf: [
161
+ {
162
+ type: "string",
163
+ minLength: 1,
164
+ maxLength: 64,
165
+ pattern: "^[a-z0-9][a-z0-9.+_-]*$"
166
+ },
167
+ {
168
+ type: "null"
169
+ }
170
+ ],
171
+ default: null
172
+ }
173
+ },
174
+ required: ["kind", "path"],
175
+ additionalProperties: false
176
+ },
177
+ {
178
+ type: "object",
179
+ properties: {
180
+ kind: {
181
+ type: "string",
182
+ const: "artifact"
183
+ },
184
+ uri: {
185
+ type: "string",
186
+ maxLength: 278,
187
+ pattern: "^docblocks:\\/\\/artifacts\\/[A-Za-z0-9][A-Za-z0-9._:-]*$"
188
+ }
189
+ },
190
+ required: ["kind", "uri"],
191
+ additionalProperties: false
192
+ },
193
+ {
194
+ type: "object",
195
+ properties: {
196
+ kind: {
197
+ type: "string",
198
+ const: "bundle"
199
+ },
200
+ markdown: {
201
+ type: "string",
202
+ maxLength: 20971520,
203
+ pattern: "^[^\\u0000\\u007f]*$"
204
+ },
205
+ assets: {
206
+ type: "array",
207
+ items: {
208
+ type: "object",
209
+ properties: {
210
+ path: {
211
+ $ref: "#/properties/source/anyOf/1/properties/path"
212
+ },
213
+ source: {
214
+ anyOf: [
215
+ {
216
+ type: "object",
217
+ properties: {
218
+ kind: {
219
+ type: "string",
220
+ const: "file"
221
+ },
222
+ rootId: {
223
+ $ref: "#/properties/source/anyOf/1/properties/rootId/anyOf/0"
224
+ },
225
+ path: {
226
+ $ref: "#/properties/source/anyOf/1/properties/path"
227
+ }
228
+ },
229
+ required: ["kind", "rootId", "path"],
230
+ additionalProperties: false
231
+ },
232
+ {
233
+ type: "object",
234
+ properties: {
235
+ kind: {
236
+ type: "string",
237
+ const: "artifact"
238
+ },
239
+ uri: {
240
+ $ref: "#/properties/source/anyOf/2/properties/uri"
241
+ }
242
+ },
243
+ required: ["kind", "uri"],
244
+ additionalProperties: false
245
+ }
246
+ ]
247
+ },
248
+ mimeType: {
249
+ anyOf: [
250
+ {
251
+ type: "string",
252
+ minLength: 3,
253
+ maxLength: 256,
254
+ pattern: "^[a-z0-9!#$&^_.+-]+\\/[a-z0-9!#$&^_.+-]+$"
255
+ },
256
+ {
257
+ type: "null"
258
+ }
259
+ ]
260
+ },
261
+ altText: {
262
+ anyOf: [
263
+ {
264
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
265
+ },
266
+ {
267
+ type: "null"
268
+ }
269
+ ]
270
+ },
271
+ credit: {
272
+ anyOf: [
273
+ {
274
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
275
+ },
276
+ {
277
+ type: "null"
278
+ }
279
+ ]
280
+ },
281
+ license: {
282
+ anyOf: [
283
+ {
284
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
285
+ },
286
+ {
287
+ type: "null"
288
+ }
289
+ ]
290
+ }
291
+ },
292
+ required: ["path", "source", "mimeType", "altText", "credit", "license"],
293
+ additionalProperties: false
294
+ },
295
+ maxItems: 256
296
+ },
297
+ name: {
298
+ anyOf: [
299
+ {
300
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
301
+ },
302
+ {
303
+ type: "null"
304
+ }
305
+ ],
306
+ default: null
307
+ }
308
+ },
309
+ required: ["kind", "markdown", "assets"],
310
+ additionalProperties: false
311
+ }
312
+ ]
313
+ },
314
+ targets: {
315
+ type: "array",
316
+ items: {
317
+ anyOf: [
318
+ {
319
+ type: "object",
320
+ properties: {
321
+ format: {
322
+ type: "string",
323
+ const: "md"
324
+ },
325
+ fidelity: {
326
+ type: "string",
327
+ enum: ["semantic"]
328
+ }
329
+ },
330
+ required: ["format"],
331
+ additionalProperties: false
332
+ },
333
+ {
334
+ type: "object",
335
+ properties: {
336
+ format: {
337
+ type: "string",
338
+ const: "dbk"
339
+ },
340
+ fidelity: {
341
+ type: "string",
342
+ enum: ["semantic", "editable-native"]
343
+ }
344
+ },
345
+ required: ["format"],
346
+ additionalProperties: false
347
+ },
348
+ {
349
+ type: "object",
350
+ properties: {
351
+ format: {
352
+ type: "string",
353
+ const: "docx"
354
+ },
355
+ fidelity: {
356
+ type: "string",
357
+ enum: ["semantic", "editable-native"]
358
+ },
359
+ title: {
360
+ type: "string",
361
+ maxLength: 4e3
362
+ },
363
+ author: {
364
+ type: "string",
365
+ maxLength: 4e3
366
+ },
367
+ description: {
368
+ type: "string",
369
+ maxLength: 8e3
370
+ },
371
+ defaultFont: {
372
+ type: "string",
373
+ maxLength: 256
374
+ },
375
+ defaultFontSize: {
376
+ type: "number",
377
+ minimum: 6,
378
+ maximum: 96
379
+ }
380
+ },
381
+ required: ["format"],
382
+ additionalProperties: false
383
+ },
384
+ {
385
+ type: "object",
386
+ properties: {
387
+ format: {
388
+ type: "string",
389
+ const: "pdf"
390
+ },
391
+ fidelity: {
392
+ type: "string",
393
+ enum: ["semantic", "rendered-fidelity", "hybrid"]
394
+ },
395
+ title: {
396
+ $ref: "#/properties/targets/items/anyOf/2/properties/title"
397
+ },
398
+ author: {
399
+ $ref: "#/properties/targets/items/anyOf/2/properties/author"
400
+ },
401
+ pageSize: {
402
+ type: "string",
403
+ enum: ["letter", "a4"]
404
+ },
405
+ margin: {
406
+ type: "number",
407
+ minimum: 0,
408
+ maximum: 288
409
+ },
410
+ defaultFontSize: {
411
+ type: "number",
412
+ minimum: 6,
413
+ maximum: 96
414
+ },
415
+ width: {
416
+ type: "integer",
417
+ minimum: 160,
418
+ maximum: 1920
419
+ },
420
+ height: {
421
+ type: "integer",
422
+ minimum: 90,
423
+ maximum: 1920
424
+ }
425
+ },
426
+ required: ["format"],
427
+ additionalProperties: false
428
+ },
429
+ {
430
+ type: "object",
431
+ properties: {
432
+ format: {
433
+ type: "string",
434
+ const: "pptx"
435
+ },
436
+ fidelity: {
437
+ type: "string",
438
+ enum: ["semantic", "editable-native", "rendered-fidelity", "hybrid"]
439
+ },
440
+ title: {
441
+ $ref: "#/properties/targets/items/anyOf/2/properties/title"
442
+ },
443
+ author: {
444
+ $ref: "#/properties/targets/items/anyOf/2/properties/author"
445
+ },
446
+ description: {
447
+ $ref: "#/properties/targets/items/anyOf/2/properties/description"
448
+ },
449
+ slideBreak: {
450
+ type: "string",
451
+ enum: ["h1", "h2", "heading"],
452
+ default: "h1",
453
+ description: "Defaults to h1: author one H1 per slide; deeper headings remain body text and no extra cover is inserted. h2 breaks at H1/H2; heading breaks at any depth. Include a title slide as an authored heading; do not add --- between heading-based slides."
454
+ },
455
+ defaultFont: {
456
+ type: "string",
457
+ maxLength: 256
458
+ },
459
+ defaultFontSize: {
460
+ type: "number",
461
+ minimum: 6,
462
+ maximum: 96
463
+ },
464
+ width: {
465
+ type: "integer",
466
+ minimum: 160,
467
+ maximum: 1920
468
+ },
469
+ height: {
470
+ type: "integer",
471
+ minimum: 90,
472
+ maximum: 1920
473
+ }
474
+ },
475
+ required: ["format"],
476
+ additionalProperties: false
477
+ },
478
+ {
479
+ type: "object",
480
+ properties: {
481
+ format: {
482
+ type: "string",
483
+ const: "xlsx"
484
+ },
485
+ fidelity: {
486
+ type: "string",
487
+ enum: ["semantic", "editable-native"]
488
+ },
489
+ title: {
490
+ $ref: "#/properties/targets/items/anyOf/2/properties/title"
491
+ },
492
+ author: {
493
+ $ref: "#/properties/targets/items/anyOf/2/properties/author"
494
+ },
495
+ sheetNamePrefix: {
496
+ type: "string",
497
+ maxLength: 31
498
+ }
499
+ },
500
+ required: ["format"],
501
+ additionalProperties: false
502
+ },
503
+ {
504
+ type: "object",
505
+ properties: {
506
+ format: {
507
+ type: "string",
508
+ const: "csv"
509
+ },
510
+ fidelity: {
511
+ type: "string",
512
+ enum: ["semantic"]
513
+ },
514
+ delimiter: {
515
+ type: "string",
516
+ minLength: 1,
517
+ maxLength: 4
518
+ },
519
+ tableIndex: {
520
+ type: "integer",
521
+ minimum: 0,
522
+ maximum: 1e4
523
+ }
524
+ },
525
+ required: ["format"],
526
+ additionalProperties: false
527
+ },
528
+ {
529
+ type: "object",
530
+ properties: {
531
+ format: {
532
+ type: "string",
533
+ const: "html"
534
+ },
535
+ fidelity: {
536
+ type: "string",
537
+ enum: ["semantic"]
538
+ },
539
+ mode: {
540
+ type: "string",
541
+ enum: ["slideshow", "static"]
542
+ },
543
+ autoPlay: {
544
+ type: "boolean"
545
+ },
546
+ title: {
547
+ $ref: "#/properties/targets/items/anyOf/2/properties/title"
548
+ }
549
+ },
550
+ required: ["format"],
551
+ additionalProperties: false
552
+ },
553
+ {
554
+ type: "object",
555
+ properties: {
556
+ format: {
557
+ type: "string",
558
+ const: "htmlzip"
559
+ },
560
+ fidelity: {
561
+ type: "string",
562
+ enum: ["semantic"]
563
+ },
564
+ mode: {
565
+ type: "string",
566
+ enum: ["slideshow", "static"]
567
+ },
568
+ autoPlay: {
569
+ type: "boolean"
570
+ },
571
+ title: {
572
+ $ref: "#/properties/targets/items/anyOf/2/properties/title"
573
+ }
574
+ },
575
+ required: ["format"],
576
+ additionalProperties: false
577
+ },
578
+ {
579
+ type: "object",
580
+ properties: {
581
+ format: {
582
+ type: "string",
583
+ const: "epub"
584
+ },
585
+ fidelity: {
586
+ type: "string",
587
+ enum: ["semantic"]
588
+ },
589
+ title: {
590
+ $ref: "#/properties/targets/items/anyOf/2/properties/title"
591
+ },
592
+ author: {
593
+ $ref: "#/properties/targets/items/anyOf/2/properties/author"
594
+ },
595
+ description: {
596
+ $ref: "#/properties/targets/items/anyOf/2/properties/description"
597
+ },
598
+ language: {
599
+ type: "string",
600
+ maxLength: 64
601
+ },
602
+ publisher: {
603
+ type: "string",
604
+ maxLength: 4e3
605
+ }
606
+ },
607
+ required: ["format"],
608
+ additionalProperties: false
609
+ },
610
+ {
611
+ type: "object",
612
+ properties: {
613
+ format: {
614
+ type: "string",
615
+ const: "mp4"
616
+ },
617
+ fidelity: {
618
+ type: "string",
619
+ enum: ["rendered-fidelity"]
620
+ },
621
+ fps: {
622
+ type: "integer",
623
+ minimum: 1,
624
+ maximum: 60
625
+ },
626
+ quality: {
627
+ type: "string",
628
+ enum: ["draft", "normal", "high"]
629
+ },
630
+ orientation: {
631
+ type: "string",
632
+ enum: ["landscape", "portrait"]
633
+ },
634
+ width: {
635
+ type: "integer",
636
+ minimum: 16,
637
+ maximum: 3840
638
+ },
639
+ height: {
640
+ type: "integer",
641
+ minimum: 16,
642
+ maximum: 3840
643
+ },
644
+ captionStyle: {
645
+ type: "string",
646
+ enum: ["standard", "social"]
647
+ },
648
+ coverPreRoll: {
649
+ type: "number",
650
+ minimum: 0,
651
+ maximum: 60
652
+ },
653
+ animationsEnabled: {
654
+ type: "boolean",
655
+ description: "Explicit rendered-media motion switch. Use it only to honor a user preference such as no motion or dynamic motion; otherwise rely on the theme/target default. It does not select an individual transition."
656
+ }
657
+ },
658
+ required: ["format"],
659
+ additionalProperties: false
660
+ },
661
+ {
662
+ type: "object",
663
+ properties: {
664
+ format: {
665
+ type: "string",
666
+ const: "gif"
667
+ },
668
+ fidelity: {
669
+ type: "string",
670
+ enum: ["rendered-fidelity"]
671
+ },
672
+ fps: {
673
+ type: "integer",
674
+ minimum: 1,
675
+ maximum: 30
676
+ },
677
+ orientation: {
678
+ type: "string",
679
+ enum: ["landscape", "portrait"]
680
+ },
681
+ width: {
682
+ type: "integer",
683
+ minimum: 16,
684
+ maximum: 1920
685
+ },
686
+ height: {
687
+ type: "integer",
688
+ minimum: 16,
689
+ maximum: 1920
690
+ },
691
+ captionStyle: {
692
+ type: "string",
693
+ enum: ["standard", "social"]
694
+ },
695
+ coverPreRoll: {
696
+ type: "number",
697
+ minimum: 0,
698
+ maximum: 60
699
+ },
700
+ animationsEnabled: {
701
+ type: "boolean",
702
+ description: "Explicit rendered-media motion switch. Use it only to honor a user preference such as no motion or dynamic motion; otherwise rely on the theme/target default. It does not select an individual transition."
703
+ },
704
+ loop: {
705
+ type: "integer",
706
+ minimum: -1,
707
+ maximum: 65535
708
+ },
709
+ maxColors: {
710
+ type: "integer",
711
+ minimum: 2,
712
+ maximum: 256
713
+ },
714
+ dither: {
715
+ type: "string",
716
+ enum: [
717
+ "none",
718
+ "bayer",
719
+ "heckbert",
720
+ "floyd_steinberg",
721
+ "sierra2",
722
+ "sierra2_4a"
723
+ ]
724
+ },
725
+ bayerScale: {
726
+ type: "integer",
727
+ minimum: 0,
728
+ maximum: 5
729
+ }
730
+ },
731
+ required: ["format"],
732
+ additionalProperties: false
733
+ },
734
+ {
735
+ type: "object",
736
+ properties: {
737
+ format: {
738
+ type: "string",
739
+ const: "png"
740
+ },
741
+ fidelity: {
742
+ type: "string",
743
+ enum: ["rendered-fidelity"]
744
+ },
745
+ resolution: {
746
+ type: "string",
747
+ enum: [
748
+ "hd",
749
+ "fhd",
750
+ "4k",
751
+ "square",
752
+ "square-2k",
753
+ "portrait",
754
+ "portrait-4k",
755
+ "standard"
756
+ ],
757
+ description: "Named output size for the Dashboard image. Mutually exclusive with width/height."
758
+ },
759
+ width: {
760
+ type: "integer",
761
+ minimum: 64,
762
+ maximum: 7680,
763
+ description: "Custom pixel width. Requires height and excludes resolution."
764
+ },
765
+ height: {
766
+ type: "integer",
767
+ minimum: 64,
768
+ maximum: 7680,
769
+ description: "Custom pixel height. Requires width and excludes resolution."
770
+ },
771
+ layout: {
772
+ type: "string",
773
+ maxLength: 64,
774
+ description: `Dashboard layout id, or "auto" to pick by block count. Omit to honor the document's own squisq-dashboard-layout frontmatter.`
775
+ },
776
+ style: {
777
+ type: "string",
778
+ enum: ["basic", "card", "panel", "accent"],
779
+ description: "Cell dressing around each block. Omit to honor the document's own squisq-dashboard-style frontmatter."
780
+ },
781
+ title: {
782
+ type: "boolean",
783
+ description: "Render the document-title band. Omit to honor the document\u2019s own setting."
784
+ }
785
+ },
786
+ required: ["format"],
787
+ additionalProperties: false
788
+ }
789
+ ]
790
+ },
791
+ minItems: 1,
792
+ maxItems: 12
793
+ },
794
+ themeId: {
795
+ type: "string",
796
+ minLength: 1,
797
+ maxLength: 256,
798
+ pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
799
+ description: "Exact Squisq theme id. Infer it from the brief when the visual direction is clear. If transformId is set and no exact theme was requested, omit themeId so the transform can apply its preferred compatible theme."
800
+ },
801
+ transformId: {
802
+ $ref: "#/properties/themeId",
803
+ description: "Optional Squisq Summarize style id. It can change content emphasis, density, pacing, and structure; leave it unset for source-preserving work unless summarization or visual restructuring is requested or permitted."
804
+ },
805
+ autoTemplates: {
806
+ type: "boolean",
807
+ description: "Enable content-aware automatic template selection. Defaults to true; explicit annotations still take precedence."
808
+ },
809
+ title: {
810
+ type: "string",
811
+ maxLength: 4e3
812
+ }
813
+ },
814
+ required: ["source", "targets"],
815
+ additionalProperties: false,
816
+ $schema: "http://json-schema.org/draft-07/schema#"
817
+ },
818
+ annotations: {
819
+ readOnlyHint: false,
820
+ destructiveHint: false,
821
+ idempotentHint: false,
822
+ openWorldHint: false
823
+ }
824
+ },
825
+ {
826
+ name: "save_artifact",
827
+ description: "Materialize an immutable artifact below a configured write root. Creation is no-replace; replacement requires the current SHA-256.",
828
+ inputSchema: {
829
+ type: "object",
830
+ properties: {
831
+ artifactUri: {
832
+ type: "string",
833
+ maxLength: 278,
834
+ pattern: "^docblocks:\\/\\/artifacts\\/[A-Za-z0-9][A-Za-z0-9._:-]*$"
835
+ },
836
+ destination: {
837
+ anyOf: [
838
+ {
839
+ type: "object",
840
+ properties: {
841
+ rootId: {
842
+ type: "string",
843
+ minLength: 1,
844
+ maxLength: 256,
845
+ pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
846
+ },
847
+ path: {
848
+ type: "string",
849
+ minLength: 1,
850
+ maxLength: 4096,
851
+ pattern: "^(?!\\/)(?![A-Za-z]:)(?!.*(?:^|\\/)(?:\\.{1,2})(?:\\/|$))(?!.*\\/\\/)(?!.*[\\\\\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"
852
+ },
853
+ ifExists: {
854
+ type: "string",
855
+ const: "error"
856
+ },
857
+ expectedSha256: {
858
+ type: "null",
859
+ default: null
860
+ }
861
+ },
862
+ required: ["rootId", "path", "ifExists"],
863
+ additionalProperties: false
864
+ },
865
+ {
866
+ type: "object",
867
+ properties: {
868
+ rootId: {
869
+ $ref: "#/properties/destination/anyOf/0/properties/rootId"
870
+ },
871
+ path: {
872
+ $ref: "#/properties/destination/anyOf/0/properties/path"
873
+ },
874
+ ifExists: {
875
+ type: "string",
876
+ const: "replace"
877
+ },
878
+ expectedSha256: {
879
+ type: "string",
880
+ pattern: "^[a-f0-9]{64}$"
881
+ }
882
+ },
883
+ required: ["rootId", "path", "ifExists", "expectedSha256"],
884
+ additionalProperties: false
885
+ }
886
+ ]
887
+ }
888
+ },
889
+ required: ["artifactUri", "destination"],
890
+ additionalProperties: false,
891
+ $schema: "http://json-schema.org/draft-07/schema#"
892
+ },
893
+ annotations: {
894
+ readOnlyHint: false,
895
+ destructiveHint: true,
896
+ idempotentHint: false,
897
+ openWorldHint: false
898
+ }
899
+ },
900
+ {
901
+ name: "preview_document",
902
+ description: "Render bounded visual previews as immutable image artifacts and report previewBasis. Markdown/DBK use source-render, imported document artifacts use reconstructed-import, and MP4/GIF sources use a native-extracted first-frame JPEG. Supports pagination and protocol progress/cancellation.",
903
+ inputSchema: {
904
+ type: "object",
905
+ properties: {
906
+ source: {
907
+ anyOf: [
908
+ {
909
+ type: "object",
910
+ properties: {
911
+ kind: {
912
+ type: "string",
913
+ const: "markdown"
914
+ },
915
+ markdown: {
916
+ type: "string",
917
+ maxLength: 20971520,
918
+ pattern: "^[^\\u0000\\u007f]*$"
919
+ },
920
+ name: {
921
+ anyOf: [
922
+ {
923
+ type: "string",
924
+ maxLength: 1024,
925
+ pattern: "^[^\\u0000\\u007f]*$"
926
+ },
927
+ {
928
+ type: "null"
929
+ }
930
+ ],
931
+ default: null
932
+ }
933
+ },
934
+ required: ["kind", "markdown"],
935
+ additionalProperties: false
936
+ },
937
+ {
938
+ type: "object",
939
+ properties: {
940
+ kind: {
941
+ type: "string",
942
+ const: "file"
943
+ },
944
+ rootId: {
945
+ anyOf: [
946
+ {
947
+ type: "string",
948
+ minLength: 1,
949
+ maxLength: 256,
950
+ pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
951
+ },
952
+ {
953
+ type: "null"
954
+ }
955
+ ],
956
+ default: null
957
+ },
958
+ path: {
959
+ type: "string",
960
+ minLength: 1,
961
+ maxLength: 4096,
962
+ pattern: "^(?!\\/)(?![A-Za-z]:)(?!.*(?:^|\\/)(?:\\.{1,2})(?:\\/|$))(?!.*\\/\\/)(?!.*[\\\\\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"
963
+ },
964
+ format: {
965
+ anyOf: [
966
+ {
967
+ type: "string",
968
+ minLength: 1,
969
+ maxLength: 64,
970
+ pattern: "^[a-z0-9][a-z0-9.+_-]*$"
971
+ },
972
+ {
973
+ type: "null"
974
+ }
975
+ ],
976
+ default: null
977
+ }
978
+ },
979
+ required: ["kind", "path"],
980
+ additionalProperties: false
981
+ },
982
+ {
983
+ type: "object",
984
+ properties: {
985
+ kind: {
986
+ type: "string",
987
+ const: "artifact"
988
+ },
989
+ uri: {
990
+ type: "string",
991
+ maxLength: 278,
992
+ pattern: "^docblocks:\\/\\/artifacts\\/[A-Za-z0-9][A-Za-z0-9._:-]*$"
993
+ }
994
+ },
995
+ required: ["kind", "uri"],
996
+ additionalProperties: false
997
+ },
998
+ {
999
+ type: "object",
1000
+ properties: {
1001
+ kind: {
1002
+ type: "string",
1003
+ const: "bundle"
1004
+ },
1005
+ markdown: {
1006
+ type: "string",
1007
+ maxLength: 20971520,
1008
+ pattern: "^[^\\u0000\\u007f]*$"
1009
+ },
1010
+ assets: {
1011
+ type: "array",
1012
+ items: {
1013
+ type: "object",
1014
+ properties: {
1015
+ path: {
1016
+ $ref: "#/properties/source/anyOf/1/properties/path"
1017
+ },
1018
+ source: {
1019
+ anyOf: [
1020
+ {
1021
+ type: "object",
1022
+ properties: {
1023
+ kind: {
1024
+ type: "string",
1025
+ const: "file"
1026
+ },
1027
+ rootId: {
1028
+ $ref: "#/properties/source/anyOf/1/properties/rootId/anyOf/0"
1029
+ },
1030
+ path: {
1031
+ $ref: "#/properties/source/anyOf/1/properties/path"
1032
+ }
1033
+ },
1034
+ required: ["kind", "rootId", "path"],
1035
+ additionalProperties: false
1036
+ },
1037
+ {
1038
+ type: "object",
1039
+ properties: {
1040
+ kind: {
1041
+ type: "string",
1042
+ const: "artifact"
1043
+ },
1044
+ uri: {
1045
+ $ref: "#/properties/source/anyOf/2/properties/uri"
1046
+ }
1047
+ },
1048
+ required: ["kind", "uri"],
1049
+ additionalProperties: false
1050
+ }
1051
+ ]
1052
+ },
1053
+ mimeType: {
1054
+ anyOf: [
1055
+ {
1056
+ type: "string",
1057
+ minLength: 3,
1058
+ maxLength: 256,
1059
+ pattern: "^[a-z0-9!#$&^_.+-]+\\/[a-z0-9!#$&^_.+-]+$"
1060
+ },
1061
+ {
1062
+ type: "null"
1063
+ }
1064
+ ]
1065
+ },
1066
+ altText: {
1067
+ anyOf: [
1068
+ {
1069
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1070
+ },
1071
+ {
1072
+ type: "null"
1073
+ }
1074
+ ]
1075
+ },
1076
+ credit: {
1077
+ anyOf: [
1078
+ {
1079
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1080
+ },
1081
+ {
1082
+ type: "null"
1083
+ }
1084
+ ]
1085
+ },
1086
+ license: {
1087
+ anyOf: [
1088
+ {
1089
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1090
+ },
1091
+ {
1092
+ type: "null"
1093
+ }
1094
+ ]
1095
+ }
1096
+ },
1097
+ required: ["path", "source", "mimeType", "altText", "credit", "license"],
1098
+ additionalProperties: false
1099
+ },
1100
+ maxItems: 256
1101
+ },
1102
+ name: {
1103
+ anyOf: [
1104
+ {
1105
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1106
+ },
1107
+ {
1108
+ type: "null"
1109
+ }
1110
+ ],
1111
+ default: null
1112
+ }
1113
+ },
1114
+ required: ["kind", "markdown", "assets"],
1115
+ additionalProperties: false
1116
+ }
1117
+ ]
1118
+ },
1119
+ startIndex: {
1120
+ type: "integer",
1121
+ minimum: 0,
1122
+ maximum: 1e5
1123
+ },
1124
+ maxItems: {
1125
+ type: "integer",
1126
+ minimum: 1,
1127
+ maximum: 20
1128
+ },
1129
+ width: {
1130
+ type: "integer",
1131
+ minimum: 160,
1132
+ maximum: 1920
1133
+ },
1134
+ height: {
1135
+ type: "integer",
1136
+ minimum: 90,
1137
+ maximum: 1920
1138
+ }
1139
+ },
1140
+ required: ["source"],
1141
+ additionalProperties: false,
1142
+ $schema: "http://json-schema.org/draft-07/schema#"
1143
+ },
1144
+ annotations: {
1145
+ readOnlyHint: false,
1146
+ destructiveHint: false,
1147
+ idempotentHint: false,
1148
+ openWorldHint: false
1149
+ }
1150
+ },
1151
+ {
1152
+ name: "inspect_document",
1153
+ description: "Inspect bounded semantic structure, block provenance, assets, metadata, theme, and diagnostics when the user asks for document analysis. Inspection is never required before conversion.",
1154
+ inputSchema: {
1155
+ type: "object",
1156
+ properties: {
1157
+ source: {
1158
+ anyOf: [
1159
+ {
1160
+ type: "object",
1161
+ properties: {
1162
+ kind: {
1163
+ type: "string",
1164
+ const: "markdown"
1165
+ },
1166
+ markdown: {
1167
+ type: "string",
1168
+ maxLength: 20971520,
1169
+ pattern: "^[^\\u0000\\u007f]*$"
1170
+ },
1171
+ name: {
1172
+ anyOf: [
1173
+ {
1174
+ type: "string",
1175
+ maxLength: 1024,
1176
+ pattern: "^[^\\u0000\\u007f]*$"
1177
+ },
1178
+ {
1179
+ type: "null"
1180
+ }
1181
+ ],
1182
+ default: null
1183
+ }
1184
+ },
1185
+ required: ["kind", "markdown"],
1186
+ additionalProperties: false
1187
+ },
1188
+ {
1189
+ type: "object",
1190
+ properties: {
1191
+ kind: {
1192
+ type: "string",
1193
+ const: "file"
1194
+ },
1195
+ rootId: {
1196
+ anyOf: [
1197
+ {
1198
+ type: "string",
1199
+ minLength: 1,
1200
+ maxLength: 256,
1201
+ pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
1202
+ },
1203
+ {
1204
+ type: "null"
1205
+ }
1206
+ ],
1207
+ default: null
1208
+ },
1209
+ path: {
1210
+ type: "string",
1211
+ minLength: 1,
1212
+ maxLength: 4096,
1213
+ pattern: "^(?!\\/)(?![A-Za-z]:)(?!.*(?:^|\\/)(?:\\.{1,2})(?:\\/|$))(?!.*\\/\\/)(?!.*[\\\\\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"
1214
+ },
1215
+ format: {
1216
+ anyOf: [
1217
+ {
1218
+ type: "string",
1219
+ minLength: 1,
1220
+ maxLength: 64,
1221
+ pattern: "^[a-z0-9][a-z0-9.+_-]*$"
1222
+ },
1223
+ {
1224
+ type: "null"
1225
+ }
1226
+ ],
1227
+ default: null
1228
+ }
1229
+ },
1230
+ required: ["kind", "path"],
1231
+ additionalProperties: false
1232
+ },
1233
+ {
1234
+ type: "object",
1235
+ properties: {
1236
+ kind: {
1237
+ type: "string",
1238
+ const: "artifact"
1239
+ },
1240
+ uri: {
1241
+ type: "string",
1242
+ maxLength: 278,
1243
+ pattern: "^docblocks:\\/\\/artifacts\\/[A-Za-z0-9][A-Za-z0-9._:-]*$"
1244
+ }
1245
+ },
1246
+ required: ["kind", "uri"],
1247
+ additionalProperties: false
1248
+ },
1249
+ {
1250
+ type: "object",
1251
+ properties: {
1252
+ kind: {
1253
+ type: "string",
1254
+ const: "bundle"
1255
+ },
1256
+ markdown: {
1257
+ type: "string",
1258
+ maxLength: 20971520,
1259
+ pattern: "^[^\\u0000\\u007f]*$"
1260
+ },
1261
+ assets: {
1262
+ type: "array",
1263
+ items: {
1264
+ type: "object",
1265
+ properties: {
1266
+ path: {
1267
+ $ref: "#/properties/source/anyOf/1/properties/path"
1268
+ },
1269
+ source: {
1270
+ anyOf: [
1271
+ {
1272
+ type: "object",
1273
+ properties: {
1274
+ kind: {
1275
+ type: "string",
1276
+ const: "file"
1277
+ },
1278
+ rootId: {
1279
+ $ref: "#/properties/source/anyOf/1/properties/rootId/anyOf/0"
1280
+ },
1281
+ path: {
1282
+ $ref: "#/properties/source/anyOf/1/properties/path"
1283
+ }
1284
+ },
1285
+ required: ["kind", "rootId", "path"],
1286
+ additionalProperties: false
1287
+ },
1288
+ {
1289
+ type: "object",
1290
+ properties: {
1291
+ kind: {
1292
+ type: "string",
1293
+ const: "artifact"
1294
+ },
1295
+ uri: {
1296
+ $ref: "#/properties/source/anyOf/2/properties/uri"
1297
+ }
1298
+ },
1299
+ required: ["kind", "uri"],
1300
+ additionalProperties: false
1301
+ }
1302
+ ]
1303
+ },
1304
+ mimeType: {
1305
+ anyOf: [
1306
+ {
1307
+ type: "string",
1308
+ minLength: 3,
1309
+ maxLength: 256,
1310
+ pattern: "^[a-z0-9!#$&^_.+-]+\\/[a-z0-9!#$&^_.+-]+$"
1311
+ },
1312
+ {
1313
+ type: "null"
1314
+ }
1315
+ ]
1316
+ },
1317
+ altText: {
1318
+ anyOf: [
1319
+ {
1320
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1321
+ },
1322
+ {
1323
+ type: "null"
1324
+ }
1325
+ ]
1326
+ },
1327
+ credit: {
1328
+ anyOf: [
1329
+ {
1330
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1331
+ },
1332
+ {
1333
+ type: "null"
1334
+ }
1335
+ ]
1336
+ },
1337
+ license: {
1338
+ anyOf: [
1339
+ {
1340
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1341
+ },
1342
+ {
1343
+ type: "null"
1344
+ }
1345
+ ]
1346
+ }
1347
+ },
1348
+ required: ["path", "source", "mimeType", "altText", "credit", "license"],
1349
+ additionalProperties: false
1350
+ },
1351
+ maxItems: 256
1352
+ },
1353
+ name: {
1354
+ anyOf: [
1355
+ {
1356
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1357
+ },
1358
+ {
1359
+ type: "null"
1360
+ }
1361
+ ],
1362
+ default: null
1363
+ }
1364
+ },
1365
+ required: ["kind", "markdown", "assets"],
1366
+ additionalProperties: false
1367
+ }
1368
+ ]
1369
+ },
1370
+ maxBlocks: {
1371
+ type: "integer",
1372
+ minimum: 1,
1373
+ maximum: 2e3
1374
+ },
1375
+ cursor: {
1376
+ anyOf: [
1377
+ {
1378
+ type: "string",
1379
+ maxLength: 256
1380
+ },
1381
+ {
1382
+ type: "null"
1383
+ }
1384
+ ]
1385
+ }
1386
+ },
1387
+ required: ["source"],
1388
+ additionalProperties: false,
1389
+ $schema: "http://json-schema.org/draft-07/schema#"
1390
+ },
1391
+ annotations: {
1392
+ readOnlyHint: true,
1393
+ destructiveHint: false,
1394
+ idempotentHint: true,
1395
+ openWorldHint: false
1396
+ }
1397
+ },
1398
+ {
1399
+ name: "list_themes",
1400
+ description: "List the linked Squisq built-in visual themes.",
1401
+ inputSchema: {
1402
+ type: "object",
1403
+ properties: {},
1404
+ additionalProperties: false,
1405
+ $schema: "http://json-schema.org/draft-07/schema#"
1406
+ },
1407
+ annotations: {
1408
+ readOnlyHint: true,
1409
+ destructiveHint: false,
1410
+ idempotentHint: true,
1411
+ openWorldHint: false
1412
+ }
1413
+ },
1414
+ {
1415
+ name: "get_authoring_context",
1416
+ description: "Optionally discover target capabilities, safe defaults, semantically described themes and Squisq Summarize styles, and exact starter annotation examples. Use these descriptions to choose for the user rather than presenting raw ids. Plain Markdown can be converted without calling this tool.",
1417
+ inputSchema: {
1418
+ type: "object",
1419
+ properties: {
1420
+ targetFormat: {
1421
+ type: "string",
1422
+ minLength: 1,
1423
+ maxLength: 64,
1424
+ pattern: "^[A-Za-z0-9][A-Za-z0-9.+_-]*$"
1425
+ },
1426
+ goal: {
1427
+ type: "string",
1428
+ enum: ["content-first", "visual-polish"]
1429
+ },
1430
+ source: {
1431
+ anyOf: [
1432
+ {
1433
+ type: "object",
1434
+ properties: {
1435
+ kind: {
1436
+ type: "string",
1437
+ const: "markdown"
1438
+ },
1439
+ markdown: {
1440
+ type: "string",
1441
+ maxLength: 20971520,
1442
+ pattern: "^[^\\u0000\\u007f]*$"
1443
+ },
1444
+ name: {
1445
+ anyOf: [
1446
+ {
1447
+ type: "string",
1448
+ maxLength: 1024,
1449
+ pattern: "^[^\\u0000\\u007f]*$"
1450
+ },
1451
+ {
1452
+ type: "null"
1453
+ }
1454
+ ],
1455
+ default: null
1456
+ }
1457
+ },
1458
+ required: ["kind", "markdown"],
1459
+ additionalProperties: false
1460
+ },
1461
+ {
1462
+ type: "object",
1463
+ properties: {
1464
+ kind: {
1465
+ type: "string",
1466
+ const: "file"
1467
+ },
1468
+ rootId: {
1469
+ anyOf: [
1470
+ {
1471
+ type: "string",
1472
+ minLength: 1,
1473
+ maxLength: 256,
1474
+ pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
1475
+ },
1476
+ {
1477
+ type: "null"
1478
+ }
1479
+ ],
1480
+ default: null
1481
+ },
1482
+ path: {
1483
+ type: "string",
1484
+ minLength: 1,
1485
+ maxLength: 4096,
1486
+ pattern: "^(?!\\/)(?![A-Za-z]:)(?!.*(?:^|\\/)(?:\\.{1,2})(?:\\/|$))(?!.*\\/\\/)(?!.*[\\\\\\u0000-\\u001f\\u007f])(?!.*\\/$).+$"
1487
+ },
1488
+ format: {
1489
+ anyOf: [
1490
+ {
1491
+ type: "string",
1492
+ minLength: 1,
1493
+ maxLength: 64,
1494
+ pattern: "^[a-z0-9][a-z0-9.+_-]*$"
1495
+ },
1496
+ {
1497
+ type: "null"
1498
+ }
1499
+ ],
1500
+ default: null
1501
+ }
1502
+ },
1503
+ required: ["kind", "path"],
1504
+ additionalProperties: false
1505
+ },
1506
+ {
1507
+ type: "object",
1508
+ properties: {
1509
+ kind: {
1510
+ type: "string",
1511
+ const: "artifact"
1512
+ },
1513
+ uri: {
1514
+ type: "string",
1515
+ maxLength: 278,
1516
+ pattern: "^docblocks:\\/\\/artifacts\\/[A-Za-z0-9][A-Za-z0-9._:-]*$"
1517
+ }
1518
+ },
1519
+ required: ["kind", "uri"],
1520
+ additionalProperties: false
1521
+ },
1522
+ {
1523
+ type: "object",
1524
+ properties: {
1525
+ kind: {
1526
+ type: "string",
1527
+ const: "bundle"
1528
+ },
1529
+ markdown: {
1530
+ type: "string",
1531
+ maxLength: 20971520,
1532
+ pattern: "^[^\\u0000\\u007f]*$"
1533
+ },
1534
+ assets: {
1535
+ type: "array",
1536
+ items: {
1537
+ type: "object",
1538
+ properties: {
1539
+ path: {
1540
+ $ref: "#/properties/source/anyOf/1/properties/path"
1541
+ },
1542
+ source: {
1543
+ anyOf: [
1544
+ {
1545
+ type: "object",
1546
+ properties: {
1547
+ kind: {
1548
+ type: "string",
1549
+ const: "file"
1550
+ },
1551
+ rootId: {
1552
+ $ref: "#/properties/source/anyOf/1/properties/rootId/anyOf/0"
1553
+ },
1554
+ path: {
1555
+ $ref: "#/properties/source/anyOf/1/properties/path"
1556
+ }
1557
+ },
1558
+ required: ["kind", "rootId", "path"],
1559
+ additionalProperties: false
1560
+ },
1561
+ {
1562
+ type: "object",
1563
+ properties: {
1564
+ kind: {
1565
+ type: "string",
1566
+ const: "artifact"
1567
+ },
1568
+ uri: {
1569
+ $ref: "#/properties/source/anyOf/2/properties/uri"
1570
+ }
1571
+ },
1572
+ required: ["kind", "uri"],
1573
+ additionalProperties: false
1574
+ }
1575
+ ]
1576
+ },
1577
+ mimeType: {
1578
+ anyOf: [
1579
+ {
1580
+ type: "string",
1581
+ minLength: 3,
1582
+ maxLength: 256,
1583
+ pattern: "^[a-z0-9!#$&^_.+-]+\\/[a-z0-9!#$&^_.+-]+$"
1584
+ },
1585
+ {
1586
+ type: "null"
1587
+ }
1588
+ ]
1589
+ },
1590
+ altText: {
1591
+ anyOf: [
1592
+ {
1593
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1594
+ },
1595
+ {
1596
+ type: "null"
1597
+ }
1598
+ ]
1599
+ },
1600
+ credit: {
1601
+ anyOf: [
1602
+ {
1603
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1604
+ },
1605
+ {
1606
+ type: "null"
1607
+ }
1608
+ ]
1609
+ },
1610
+ license: {
1611
+ anyOf: [
1612
+ {
1613
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1614
+ },
1615
+ {
1616
+ type: "null"
1617
+ }
1618
+ ]
1619
+ }
1620
+ },
1621
+ required: ["path", "source", "mimeType", "altText", "credit", "license"],
1622
+ additionalProperties: false
1623
+ },
1624
+ maxItems: 256
1625
+ },
1626
+ name: {
1627
+ anyOf: [
1628
+ {
1629
+ $ref: "#/properties/source/anyOf/0/properties/name/anyOf/0"
1630
+ },
1631
+ {
1632
+ type: "null"
1633
+ }
1634
+ ],
1635
+ default: null
1636
+ }
1637
+ },
1638
+ required: ["kind", "markdown", "assets"],
1639
+ additionalProperties: false
1640
+ }
1641
+ ]
1642
+ },
1643
+ maxBlocks: {
1644
+ type: "integer",
1645
+ minimum: 1,
1646
+ maximum: 100
1647
+ }
1648
+ },
1649
+ additionalProperties: false,
1650
+ $schema: "http://json-schema.org/draft-07/schema#"
1651
+ },
1652
+ annotations: {
1653
+ readOnlyHint: true,
1654
+ destructiveHint: false,
1655
+ idempotentHint: true,
1656
+ openWorldHint: false
1657
+ }
1658
+ }
1659
+ ]
1660
+ };
25
1661
 
26
1662
  // src/harness/paths.ts
27
1663
  import { isAbsolute, join, relative, resolve, sep } from "path";
@@ -117,6 +1753,7 @@ var HarnessSession = class {
117
1753
  roots;
118
1754
  rootsProvider = null;
119
1755
  current = new AsyncLocalStorage();
1756
+ closers = [];
120
1757
  constructor(opts) {
121
1758
  this.opts = opts;
122
1759
  this.client = opts.client;
@@ -153,7 +1790,13 @@ var HarnessSession = class {
153
1790
  run(binding, fn) {
154
1791
  return this.current.run(binding, async () => fn(await this.api()));
155
1792
  }
1793
+ /** Run `fn` when the app disconnects: processes a tool started for it. */
1794
+ onClose(fn) {
1795
+ this.closers.push(fn);
1796
+ }
156
1797
  async close() {
1798
+ await Promise.all(this.closers.map((fn) => fn().catch(() => {
1799
+ })));
157
1800
  await this.local?.close().catch(() => {
158
1801
  });
159
1802
  this.local = null;
@@ -260,6 +1903,7 @@ var HarnessSession = class {
260
1903
  };
261
1904
 
262
1905
  // src/harness/tools.ts
1906
+ import { readFileSync, statSync } from "fs";
263
1907
  import { readFile, stat } from "fs/promises";
264
1908
  import { extname, isAbsolute as isAbsolute3, join as join2, sep as sep2 } from "path";
265
1909
  import {
@@ -271,7 +1915,7 @@ import {
271
1915
  } from "@bendyline/gezel";
272
1916
  import { GezelApiError, apiErrorMessage } from "@bendyline/gezel-client/node";
273
1917
  import { MEMORY_KINDS } from "@bendyline/gezel/runtime";
274
- import { z } from "zod";
1918
+ import { z as z2 } from "zod";
275
1919
  var UNBOUND_PROJECT = "default";
276
1920
  var MAX_IMAGE_BYTES = 20 * 1024 * 1024;
277
1921
  var SEARCH_SCOPES = ["folder", "library", "memories", "knowledge"];
@@ -376,20 +2020,82 @@ function renderOverview(binding, hit, area) {
376
2020
  return `- Overview of ${where} (Gezel's summary)${summary ? `
377
2021
  ${summary}` : ""}`;
378
2022
  }
379
- function renderFileHit(binding, group) {
2023
+ var MAX_LOCATE_BYTES = 2e6;
2024
+ var SHOWN_LINES = 2;
2025
+ var SHOWN_LINE_CHARS = 140;
2026
+ var readLinesSync = (path) => {
2027
+ try {
2028
+ if (statSync(path).size > MAX_LOCATE_BYTES) return null;
2029
+ return readFileSync(path, "utf8").split(/\r?\n/);
2030
+ } catch {
2031
+ return null;
2032
+ }
2033
+ };
2034
+ function queryWords(query) {
2035
+ const words = query.toLowerCase().match(/[a-z0-9_]{4,}/g) ?? [];
2036
+ return [...new Set(words.map((w) => w.replace(/(ies|es|s|ed|ing)$/, "")))].filter(
2037
+ (w) => w.length >= 3
2038
+ );
2039
+ }
2040
+ function locateSnippet(fileLines, snippet, from, to) {
2041
+ const lines = snippet.split(/\r?\n/);
2042
+ const lo = Math.max(0, from - 1);
2043
+ const hi = Math.min(fileLines.length, Math.max(to, from));
2044
+ for (let k = 0; k < Math.min(lines.length, 12); k++) {
2045
+ const probe = lines[k].trim();
2046
+ if (probe.length < 12) continue;
2047
+ for (let i = lo; i < hi; i++) {
2048
+ if (fileLines[i].includes(probe)) return { start: i - k + 1, lines };
2049
+ }
2050
+ }
2051
+ return null;
2052
+ }
2053
+ function shownLines(located, words) {
2054
+ const candidates = located.lines.map((text2, i) => ({ n: located.start + i, text: text2.trim() })).filter((l) => l.text.length > 0 && !/^[{}()[\];,]+$/.test(l.text) && !l.text.endsWith("\u2026"));
2055
+ const score = (text2) => words.filter((w) => text2.toLowerCase().includes(w)).length;
2056
+ const ranked = [...candidates].sort((a, b) => score(b.text) - score(a.text) || a.n - b.n);
2057
+ const pool = ranked.length > 0 && score(ranked[0].text) > 0 ? ranked : candidates;
2058
+ return pool.slice(0, SHOWN_LINES).sort((a, b) => a.n - b.n);
2059
+ }
2060
+ function renderFileHit(binding, group, words = [], readLines = readLinesSync) {
380
2061
  const first = group[0];
381
- const ranges = [
382
- ...new Set(
383
- group.filter((h) => h.line !== void 0).map((h) => h.lineEnd && h.lineEnd !== h.line ? `${h.line}-${h.lineEnd}` : `${h.line}`)
384
- )
385
- ].slice(0, 4);
386
2062
  const abs = absoluteForHit(binding, first);
387
2063
  const label = abs ?? (first.projectName ? `${first.projectName}: ${first.path ?? first.title}` : first.path ?? first.title);
2064
+ const fileLines = abs && group.some((h) => h.snippet && h.line !== void 0) ? readLines(abs) : null;
2065
+ const ranges = [];
2066
+ let shown = [];
2067
+ let inside = "";
2068
+ for (const h of group) {
2069
+ if (h.line === void 0) continue;
2070
+ const located = fileLines && h.snippet ? locateSnippet(fileLines, h.snippet, h.line, h.lineEnd ?? h.line) : null;
2071
+ if (!located) {
2072
+ ranges.push(h.lineEnd && h.lineEnd !== h.line ? `${h.line}-${h.lineEnd}` : `${h.line}`);
2073
+ continue;
2074
+ }
2075
+ const end = Math.min(located.start + located.lines.length - 1, fileLines.length);
2076
+ ranges.push(end > located.start ? `${located.start}-${end}` : `${located.start}`);
2077
+ if (h === first) {
2078
+ shown = shownLines(located, words);
2079
+ const span = (h.lineEnd ?? h.line) - h.line;
2080
+ const head = fileLines[h.line - 1]?.trim();
2081
+ if (head && span > located.lines.length && h.line < located.start) {
2082
+ inside = ` (inside \`${head.slice(0, 60)}\`, ${h.line}-${h.lineEnd})`;
2083
+ }
2084
+ }
2085
+ }
2086
+ const where = ranges.length ? `:${[...new Set(ranges)].slice(0, 4).join(", ")}` : "";
2087
+ if (shown.length > 0) {
2088
+ const body = shown.map((l) => ` ${l.n}| ${l.text.slice(0, SHOWN_LINE_CHARS)}`).join("\n");
2089
+ return `- ${label}${where}${inside}
2090
+ ${body}`;
2091
+ }
388
2092
  const snippet = first.snippet?.replace(/\s+/g, " ").trim().slice(0, 280) ?? "";
389
- return `- ${label}${ranges.length ? `:${ranges.join(", ")}` : ""}${snippet ? `
2093
+ return `- ${label}${where}${snippet ? `
390
2094
  ${snippet}` : ""}`;
391
2095
  }
392
2096
  function arrangeSearchResults(binding, results, opts) {
2097
+ const words = opts.query ? queryWords(opts.query) : [];
2098
+ const fileHit = (group) => renderFileHit(binding, group, words, opts.readLines ?? readLinesSync);
393
2099
  const groups = /* @__PURE__ */ new Map();
394
2100
  const side = [];
395
2101
  const onlyMedia = results.every((hit) => !isFolderHit(hit) || hit.media !== void 0);
@@ -412,9 +2118,9 @@ function arrangeSearchResults(binding, results, opts) {
412
2118
  const docGroups = all.filter(([path]) => isDocPath(path));
413
2119
  const folder = code.slice(0, opts.maxResults).map(([, group]) => {
414
2120
  const area = overviewArea(group[0]);
415
- return area === null ? renderFileHit(binding, group) : renderOverview(binding, group[0], area);
2121
+ return area === null ? fileHit(group) : renderOverview(binding, group[0], area);
416
2122
  });
417
- const docs = docGroups.slice(0, folder.length === 0 ? opts.maxResults : MAX_DOC_HITS).map(([, group]) => renderFileHit(binding, group));
2123
+ const docs = docGroups.slice(0, folder.length === 0 ? opts.maxResults : MAX_DOC_HITS).map(([, group]) => fileHit(group));
418
2124
  const anyFolder = folder.length + docs.length > 0;
419
2125
  const keptSide = side.filter((hit) => opts.sideByName || !anyFolder || hit.tier === "strong").slice(0, opts.sideByName || !anyFolder ? opts.maxResults : MAX_SIDE_HITS).map((hit) => renderHit(binding, hit));
420
2126
  return { folder, docs, side: keptSide };
@@ -438,20 +2144,21 @@ function registerHarnessTools(server, session) {
438
2144
  {
439
2145
  description: HARNESS_TOOL_DESCRIPTIONS.search,
440
2146
  inputSchema: {
441
- query: z.string().min(1).max(400).describe("What to look for, in plain words."),
442
- scopes: z.array(z.enum(SEARCH_SCOPES)).optional().describe(
2147
+ query: z2.string().trim().min(1).max(400).describe("What to look for, in plain words."),
2148
+ scopes: z2.array(z2.enum(SEARCH_SCOPES)).optional().describe(
443
2149
  "Which of folder, library, memories, knowledge to search. Default: folder, library and memories. Add knowledge for installed reference catalogs."
444
2150
  ),
445
- catalogs: z.array(z.string().min(1)).max(64).optional().describe("Search only these knowledge catalogs (ids from gezel_status)."),
446
- pathPrefix: z.string().min(1).optional().describe(
2151
+ catalogs: z2.array(z2.string().min(1)).max(64).optional().describe("Search only these knowledge catalogs (ids from gezel_status)."),
2152
+ pathPrefix: z2.string().min(1).optional().describe(
447
2153
  "Only files under this folder: an absolute path, or one relative to this folder."
448
2154
  ),
449
- maxResults: z.number().int().positive().max(50).optional().describe("Default 20."),
450
- cursor: z.number().int().min(0).max(1e4).optional().describe("From a previous truncated search.")
2155
+ maxResults: z2.number().int().positive().max(50).optional().describe("Default 10."),
2156
+ cursor: z2.number().int().min(0).max(1e4).optional().describe("From a previous truncated search.")
451
2157
  },
452
2158
  annotations: { readOnlyHint: true }
453
2159
  },
454
2160
  async (args) => guarded(async () => {
2161
+ const query = args.query;
455
2162
  const binding = await session.bind(args.pathPrefix);
456
2163
  const scopes = args.catalogs ? ["knowledge"] : args.scopes?.length ? args.scopes : DEFAULT_SCOPES;
457
2164
  const sources = harnessSources(binding, scopes);
@@ -472,12 +2179,12 @@ function registerHarnessTools(server, session) {
472
2179
  if (args.catalogs && catalogs?.length === 0) {
473
2180
  return failure("Those knowledge catalogs are not available to other apps.");
474
2181
  }
475
- const maxResults = args.maxResults ?? 15;
2182
+ const maxResults = args.maxResults ?? 10;
476
2183
  const fetched = Math.min(100, maxResults * 3);
477
2184
  const res = await session.run(
478
2185
  binding,
479
2186
  (api) => api.toolSearch(boundProjectId(binding) ?? UNBOUND_PROJECT, {
480
- query: args.query,
2187
+ query,
481
2188
  includeShared: sources.includes("shared"),
482
2189
  sources,
483
2190
  maxResults: fetched,
@@ -488,7 +2195,8 @@ function registerHarnessTools(server, session) {
488
2195
  );
489
2196
  const { folder, docs, side } = arrangeSearchResults(binding, res.results, {
490
2197
  maxResults,
491
- sideByName: Boolean(args.catalogs || args.scopes?.length)
2198
+ sideByName: Boolean(args.catalogs || args.scopes?.length),
2199
+ query
492
2200
  });
493
2201
  const lines = [...folder];
494
2202
  if (docs.length > 0) {
@@ -519,7 +2227,7 @@ function registerHarnessTools(server, session) {
519
2227
  {
520
2228
  description: HARNESS_TOOL_DESCRIPTIONS.read_doc_as_markdown,
521
2229
  inputSchema: {
522
- path: z.string().min(1).describe("The document: an absolute path, or one relative to this folder.")
2230
+ path: z2.string().min(1).describe("The document: an absolute path, or one relative to this folder.")
523
2231
  },
524
2232
  annotations: { readOnlyHint: true }
525
2233
  },
@@ -562,7 +2270,7 @@ ${res.content}`);
562
2270
  {
563
2271
  description: HARNESS_TOOL_DESCRIPTIONS.list_documents,
564
2272
  inputSchema: {
565
- path: z.string().min(1).optional().describe("A subfolder of the library to list.")
2273
+ path: z2.string().min(1).optional().describe("A subfolder of the library to list.")
566
2274
  },
567
2275
  annotations: { readOnlyHint: true }
568
2276
  },
@@ -588,7 +2296,7 @@ ${res.content}`);
588
2296
  {
589
2297
  description: HARNESS_TOOL_DESCRIPTIONS.read_document,
590
2298
  inputSchema: {
591
- path: z.string().min(1).describe(
2299
+ path: z2.string().min(1).describe(
592
2300
  "A library document (absolute, or relative to the library), or a knowledge:// address."
593
2301
  )
594
2302
  },
@@ -628,7 +2336,7 @@ ${passage.text}`);
628
2336
 
629
2337
  ${doc.markdown}`);
630
2338
  }
631
- const where = rootedPath(binding, args.path);
2339
+ const where = isAbsolute3(args.path) ? rootedPath(binding, args.path) : null;
632
2340
  if (where && where.root !== "library") {
633
2341
  return failure(
634
2342
  `${where.abs} is not in the shared library. Use read_doc_as_markdown for files in this folder.`
@@ -644,8 +2352,8 @@ ${doc.markdown}`);
644
2352
  {
645
2353
  description: HARNESS_TOOL_DESCRIPTIONS.search_memory,
646
2354
  inputSchema: {
647
- query: z.string().min(1).max(400).describe("What to recall, in plain words."),
648
- maxResults: z.number().int().positive().max(30).optional().describe("Default 10.")
2355
+ query: z2.string().min(1).max(400).describe("What to recall, in plain words."),
2356
+ maxResults: z2.number().int().positive().max(30).optional().describe("Default 10.")
649
2357
  },
650
2358
  annotations: { readOnlyHint: true }
651
2359
  },
@@ -673,8 +2381,8 @@ ${doc.markdown}`);
673
2381
  {
674
2382
  description: HARNESS_TOOL_DESCRIPTIONS.save_memory,
675
2383
  inputSchema: {
676
- text: z.string().min(3).max(2e3).describe("The fact, as one or two self-contained sentences."),
677
- kind: z.enum(MEMORY_KINDS).optional().describe(
2384
+ text: z2.string().min(3).max(2e3).describe("The fact, as one or two self-contained sentences."),
2385
+ kind: z2.enum(MEMORY_KINDS).optional().describe(
678
2386
  "fact (default), decision, pref (a preference), status, correction, or example."
679
2387
  )
680
2388
  }
@@ -704,11 +2412,11 @@ ${doc.markdown}`);
704
2412
  {
705
2413
  description: HARNESS_TOOL_DESCRIPTIONS.describe_image,
706
2414
  inputSchema: {
707
- path: z.string().min(1).describe("The image: an absolute path, or one relative to this folder."),
708
- mode: z.enum(["auto", "describe", "ocr", "ui", "extract"]).optional().describe(
2415
+ path: z2.string().min(1).describe("The image: an absolute path, or one relative to this folder."),
2416
+ mode: z2.enum(["auto", "describe", "ocr", "ui", "extract"]).optional().describe(
709
2417
  "auto (default), describe, ocr (text in the image), ui (a screenshot), extract (needs schema)."
710
2418
  ),
711
- schema: z.record(z.string(), z.unknown()).optional().describe("JSON Schema for extract mode.")
2419
+ schema: z2.record(z2.string(), z2.unknown()).optional().describe("JSON Schema for extract mode.")
712
2420
  },
713
2421
  annotations: { readOnlyHint: true }
714
2422
  },
@@ -753,11 +2461,11 @@ ${doc.markdown}`);
753
2461
  {
754
2462
  description: HARNESS_TOOL_DESCRIPTIONS.generate_image,
755
2463
  inputSchema: {
756
- prompt: z.string().min(1).max(4e3).describe("What the image should show, or the edit to make to inputImages."),
757
- aspectRatio: z.enum(IMAGE_ASPECT_RATIOS).optional(),
758
- quality: z.enum(IMAGE_QUALITIES).optional().describe("'draft', 'standard' (default) or 'high'."),
759
- negativePrompt: z.string().max(2e3).optional().describe("Things to keep out of the image."),
760
- inputImages: z.array(z.string().min(1)).max(4).optional().describe("Images to edit or combine: absolute paths, or paths relative to this folder.")
2464
+ prompt: z2.string().min(1).max(4e3).describe("What the image should show, or the edit to make to inputImages."),
2465
+ aspectRatio: z2.enum(IMAGE_ASPECT_RATIOS).optional(),
2466
+ quality: z2.enum(IMAGE_QUALITIES).optional().describe("'draft', 'standard' (default) or 'high'."),
2467
+ negativePrompt: z2.string().max(2e3).optional().describe("Things to keep out of the image."),
2468
+ inputImages: z2.array(z2.string().min(1)).max(4).optional().describe("Images to edit or combine: absolute paths, or paths relative to this folder.")
761
2469
  }
762
2470
  },
763
2471
  async (args) => guarded(async () => {
@@ -789,9 +2497,11 @@ ${doc.markdown}`);
789
2497
  const saved = artifactsDir ? join2(artifactsDir, res.artifactPath) : res.artifactPath;
790
2498
  const content = [];
791
2499
  if (res.b64Png) content.push({ type: "image", data: res.b64Png, mimeType: "image/png" });
2500
+ const skipped = res.meta.img2imgSkippedReason ? `This image engine can't edit images (${res.meta.img2imgSkippedReason}), so it ignored inputImages and made a new image from the prompt alone. To change an image, describe the whole picture you want. ` : "";
2501
+ const settings = res.meta.settingsNotes?.length ? `Image settings: ${res.meta.settingsNotes.join(" ")} ` : "";
792
2502
  content.push({
793
2503
  type: "text",
794
- text: `Saved to ${saved} (${res.meta.widthPx}x${res.meta.heightPx}, ${res.meta.model}). Copy it into the folder with your own file tools if it belongs there.`
2504
+ text: `${skipped}${settings}Saved to ${saved} (${res.meta.widthPx}x${res.meta.heightPx}, ${res.meta.model}). Copy it into the folder with your own file tools if it belongs there.`
795
2505
  });
796
2506
  return { content };
797
2507
  })
@@ -848,7 +2558,266 @@ async function readAllowedImage(binding, path) {
848
2558
  return { data: (await readFile(where.abs)).toString("base64"), mimeType };
849
2559
  }
850
2560
 
2561
+ // src/harness/documents.ts
2562
+ var TOOLS = docblocks_tools_default.tools;
2563
+ var SOURCE_ARGS = {
2564
+ convert_document: ["source"],
2565
+ get_authoring_context: ["source"],
2566
+ inspect_document: ["source"],
2567
+ preview_document: ["source"]
2568
+ };
2569
+ var CALL_TIMEOUT_MS = 10 * 6e4;
2570
+ var OUTDATED = "This version of Gezel can't make documents for other apps yet. Update Gezel, then try again.";
2571
+ function appSaveSchema(schema) {
2572
+ const destination = schema.properties.destination;
2573
+ const path = destination?.anyOf?.[0]?.properties?.path;
2574
+ return {
2575
+ ...schema,
2576
+ properties: {
2577
+ ...schema.properties,
2578
+ destination: {
2579
+ type: "object",
2580
+ properties: {
2581
+ path: {
2582
+ ...path,
2583
+ description: "A file name, or a path inside Gezel's output folder, such as report.docx."
2584
+ },
2585
+ ifExists: { type: "string", enum: ["error", "replace"], default: "error" },
2586
+ expectedSha256: {
2587
+ type: "string",
2588
+ pattern: "^[a-f0-9]{64}$",
2589
+ description: "With ifExists replace: the current file's SHA-256."
2590
+ }
2591
+ },
2592
+ required: ["path"],
2593
+ additionalProperties: false
2594
+ }
2595
+ }
2596
+ };
2597
+ }
2598
+ function listedAs(json) {
2599
+ const schema = z3.object({}).loose();
2600
+ schema._zod.toJSONSchema = () => structuredClone(json);
2601
+ return schema;
2602
+ }
2603
+ var DocblocksRuntime = class _DocblocksRuntime {
2604
+ constructor(client, readRoot, outputDir, writeRootId) {
2605
+ this.client = client;
2606
+ this.readRoot = readRoot;
2607
+ this.outputDir = outputDir;
2608
+ this.writeRootId = writeRootId;
2609
+ }
2610
+ client;
2611
+ readRoot;
2612
+ outputDir;
2613
+ writeRootId;
2614
+ static async start(binding) {
2615
+ const docs = binding.info?.documents;
2616
+ if (!docs) throw new Error(OUTDATED);
2617
+ const readRoot = binding.info?.project?.workingDir ?? null;
2618
+ const outputDir = await outputDirFor(binding);
2619
+ const args = [docs.entry, "mcp"];
2620
+ if (readRoot) args.push("--allow-read", readRoot);
2621
+ args.push("--allow-write", outputDir);
2622
+ const env = {};
2623
+ if (docs.browsersPath) env.PLAYWRIGHT_BROWSERS_PATH = docs.browsersPath;
2624
+ if (process.env.SQUISQ_FFMPEG) env.SQUISQ_FFMPEG = process.env.SQUISQ_FFMPEG;
2625
+ const client = new Client({ name: "gezel-harness", version: "1.0.0" });
2626
+ await client.connect(
2627
+ new StdioClientTransport({ command: process.execPath, args, env, stderr: "ignore" })
2628
+ );
2629
+ const listed2 = await client.callTool({ name: "list_roots", arguments: {} });
2630
+ const writeRootId = writableRoot(listed2);
2631
+ if (!writeRootId) {
2632
+ await client.close().catch(() => {
2633
+ });
2634
+ throw new Error("Gezel's document tools started without a folder to save into.");
2635
+ }
2636
+ return new _DocblocksRuntime(client, readRoot, outputDir, writeRootId);
2637
+ }
2638
+ async call(name, args) {
2639
+ return await this.client.callTool({ name, arguments: args }, void 0, {
2640
+ timeout: CALL_TIMEOUT_MS,
2641
+ resetTimeoutOnProgress: true
2642
+ });
2643
+ }
2644
+ close() {
2645
+ return this.client.close().catch(() => {
2646
+ });
2647
+ }
2648
+ };
2649
+ async function outputDirFor(binding) {
2650
+ const artifactsDir = binding.info?.artifactsDir;
2651
+ if (artifactsDir) {
2652
+ const dir2 = join3(artifactsDir, "documents");
2653
+ try {
2654
+ await mkdir(dir2, { recursive: true });
2655
+ await access(dir2, constants.W_OK);
2656
+ return dir2;
2657
+ } catch {
2658
+ }
2659
+ }
2660
+ const dir = join3(tmpdir(), "gezel-documents", boundProjectId(binding) ?? "default");
2661
+ await mkdir(dir, { recursive: true });
2662
+ return dir;
2663
+ }
2664
+ function writableRoot(listed2) {
2665
+ const text2 = listed2.content.filter((c) => c.type === "text").map((c) => c.text).join("");
2666
+ const structured = listed2.structuredContent;
2667
+ let roots = structured?.roots;
2668
+ if (!Array.isArray(roots)) {
2669
+ try {
2670
+ roots = JSON.parse(text2).roots;
2671
+ } catch {
2672
+ return null;
2673
+ }
2674
+ }
2675
+ if (!Array.isArray(roots)) return null;
2676
+ const root = roots.find((r) => r.write === true);
2677
+ return typeof root?.id === "string" ? root.id : null;
2678
+ }
2679
+ function appSource(binding, runtime, source) {
2680
+ const path = typeof source === "string" && !source.startsWith("docblocks://") ? source : source && typeof source === "object" && source.kind === "file" ? source.path : void 0;
2681
+ if (typeof path !== "string") return { source };
2682
+ if (!runtime.readRoot) {
2683
+ return { error: "This app is not working in a Gezel folder, so pass Markdown, not a file." };
2684
+ }
2685
+ const rel = relativeInside(runtime.readRoot, absoluteFromApp(binding, path));
2686
+ if (!rel) return { error: `${path} is not inside ${runtime.readRoot}.` };
2687
+ const rest = typeof source === "object" ? source : {};
2688
+ const { rootId: _rootId, ...file } = rest;
2689
+ return { source: { ...file, kind: "file", path: rel } };
2690
+ }
2691
+ function appDestination(runtime, destination) {
2692
+ const given = typeof destination === "string" ? { path: destination } : destination && typeof destination === "object" ? destination : null;
2693
+ const raw = typeof given?.path === "string" ? given.path.trim() : "";
2694
+ if (!raw) return { error: 'save_artifact needs `destination: {"path": "report.docx"}`.' };
2695
+ const path = isAbsolute4(raw) ? relativeInside(runtime.outputDir, resolve3(raw)) : raw.replaceAll("\\", "/").replace(/^(\.\/)+/, "");
2696
+ if (!path) {
2697
+ return {
2698
+ error: `Gezel saves documents in its own folder (${runtime.outputDir}): pass a file name such as report.docx, then copy the file where it belongs.`
2699
+ };
2700
+ }
2701
+ const target = join3(runtime.outputDir, path);
2702
+ const replace = given?.ifExists === "replace" && existsSync(target);
2703
+ const free = replace ? path : freeName(runtime.outputDir, path);
2704
+ const expectedSha256 = !replace ? null : typeof given?.expectedSha256 === "string" ? given.expectedSha256 : createHash("sha256").update(readFileSync2(target)).digest("hex");
2705
+ return {
2706
+ destination: {
2707
+ rootId: runtime.writeRootId,
2708
+ path: free,
2709
+ ifExists: replace ? "replace" : "error",
2710
+ expectedSha256
2711
+ },
2712
+ saved: join3(runtime.outputDir, free),
2713
+ ...free !== path ? { renamedFrom: path } : {}
2714
+ };
2715
+ }
2716
+ function freeName(dir, path) {
2717
+ if (!existsSync(join3(dir, path))) return path;
2718
+ const slash = path.lastIndexOf("/");
2719
+ const base = path.slice(slash + 1);
2720
+ const dot = base.lastIndexOf(".");
2721
+ const stem = dot > 0 ? base.slice(0, dot) : base;
2722
+ const ext = dot > 0 ? base.slice(dot) : "";
2723
+ for (let n = 2; ; n++) {
2724
+ const candidate = `${path.slice(0, slash + 1)}${stem} (${n})${ext}`;
2725
+ if (!existsSync(join3(dir, candidate))) return candidate;
2726
+ }
2727
+ }
2728
+ function registerHarnessDocumentTools(server, session) {
2729
+ const runtimes = /* @__PURE__ */ new Map();
2730
+ session.onClose(async () => {
2731
+ const all = [...runtimes.values()];
2732
+ runtimes.clear();
2733
+ await Promise.all(all.map((p) => p.then((r) => r.close()).catch(() => {
2734
+ })));
2735
+ });
2736
+ const runtimeFor = (binding) => {
2737
+ let runtime = runtimes.get(binding.key);
2738
+ if (!runtime) {
2739
+ runtime = DocblocksRuntime.start(binding);
2740
+ runtimes.set(binding.key, runtime);
2741
+ runtime.catch(() => runtimes.delete(binding.key));
2742
+ }
2743
+ return runtime;
2744
+ };
2745
+ for (const name of HARNESS_DOCUMENT_TOOL_NAMES) {
2746
+ const tool = TOOLS.find((t) => t.name === name);
2747
+ if (!tool) continue;
2748
+ const inputSchema = name === "save_artifact" ? appSaveSchema(tool.inputSchema) : tool.inputSchema;
2749
+ server.registerTool(
2750
+ name,
2751
+ {
2752
+ description: `${tool.description} ${HARNESS_DOCUMENT_TOOL_NOTES[name]}`,
2753
+ inputSchema: listedAs(inputSchema),
2754
+ ...tool.annotations ? { annotations: tool.annotations } : {}
2755
+ },
2756
+ async (args) => guarded(async () => {
2757
+ if (missingArguments(inputSchema, args).length > 0) {
2758
+ return failure(argumentHelp(name, inputSchema, args));
2759
+ }
2760
+ const binding = await session.bind();
2761
+ if (!binding.info?.documents) return failure(OUTDATED);
2762
+ let runtime;
2763
+ try {
2764
+ runtime = await runtimeFor(binding);
2765
+ } catch (err) {
2766
+ const reason = err instanceof Error ? err.message : String(err);
2767
+ return failure(
2768
+ reason === OUTDATED ? reason : `Gezel could not start its document tools: ${reason}`
2769
+ );
2770
+ }
2771
+ const forwarded = { ...args };
2772
+ for (const key of SOURCE_ARGS[name] ?? []) {
2773
+ if (forwarded[key] === void 0) continue;
2774
+ const mapped = appSource(binding, runtime, forwarded[key]);
2775
+ if ("error" in mapped) return failure(mapped.error);
2776
+ forwarded[key] = mapped.source;
2777
+ }
2778
+ let saved = null;
2779
+ let renamedFrom;
2780
+ if (name === "save_artifact") {
2781
+ const mapped = appDestination(runtime, forwarded.destination);
2782
+ if ("error" in mapped) return failure(mapped.error);
2783
+ forwarded.destination = mapped.destination;
2784
+ saved = mapped.saved;
2785
+ renamedFrom = mapped.renamedFrom;
2786
+ await mkdir(dirname(saved), { recursive: true });
2787
+ }
2788
+ const { structuredContent, ...result } = await runtime.call(name, forwarded);
2789
+ const failed = result.isError === true || structuredContent?.kind === "error";
2790
+ if (failed) result.isError = true;
2791
+ if (saved && !failed) {
2792
+ const renamed = renamedFrom ? `Gezel's folder already had a ${renamedFrom}, so this one is named ${basename(saved)}. ` : "";
2793
+ result.content = [
2794
+ ...result.content,
2795
+ {
2796
+ type: "text",
2797
+ text: `${renamed}Saved to ${saved}. Copy it into the folder with your own file tools if it belongs there.`
2798
+ }
2799
+ ];
2800
+ }
2801
+ return result;
2802
+ })
2803
+ );
2804
+ }
2805
+ }
2806
+
851
2807
  // src/harness/issues.ts
2808
+ import { join as join4 } from "path";
2809
+ import {
2810
+ HARNESS_PROMPTS,
2811
+ HARNESS_PROMPT_NAMES,
2812
+ HARNESS_TOOL_DESCRIPTIONS as HARNESS_TOOL_DESCRIPTIONS2,
2813
+ ISSUE_VERDICT_KINDS,
2814
+ MAX_APP_ISSUE_VERDICTS_PER_CALL,
2815
+ harnessPromptCount,
2816
+ renderEmptyIssuePrompt,
2817
+ renderHarnessIssuePrompt,
2818
+ renderIssueBatch
2819
+ } from "@bendyline/gezel";
2820
+ import { z as z4 } from "zod";
852
2821
  var UPDATE_GEZEL = "This version of Gezel cannot hand issues to other apps. Update Gezel to use this tool.";
853
2822
  var NO_PROJECT = "This app isn't working in a folder Gezel knows, so there are no issues to check. Start the app in a folder Gezel has added.";
854
2823
  function issuesBlocked(binding, need) {
@@ -866,7 +2835,7 @@ async function fetchBatch(session, binding, req) {
866
2835
  const queue = await session.run(binding, (api) => api.issueTriage.handoffQueue(id, req));
867
2836
  const workingDir = binding.info?.project?.workingDir;
868
2837
  return {
869
- text: renderIssueBatch(queue, (rel) => workingDir ? join3(workingDir, rel) : rel),
2838
+ text: renderIssueBatch(queue, (rel) => workingDir ? join4(workingDir, rel) : rel),
870
2839
  empty: queue.count === 0
871
2840
  };
872
2841
  }
@@ -876,12 +2845,12 @@ function registerHarnessIssueTools(server, session) {
876
2845
  {
877
2846
  description: HARNESS_TOOL_DESCRIPTIONS2.list_issues,
878
2847
  inputSchema: {
879
- limit: z2.number().int().positive().max(50).optional().describe("Default 20."),
880
- severity: z2.enum(["major", "minor", "info"]).optional(),
881
- pathPrefix: z2.string().min(1).optional().describe(
2848
+ limit: z4.number().int().positive().max(50).optional().describe("Default 20."),
2849
+ severity: z4.enum(["major", "minor", "info"]).optional(),
2850
+ pathPrefix: z4.string().min(1).optional().describe(
882
2851
  "Only issues under this folder: an absolute path, or one relative to this folder."
883
2852
  ),
884
- includeInfo: z2.boolean().optional().describe("Include info-level leads. Default false.")
2853
+ includeInfo: z4.boolean().optional().describe("Include info-level leads. Default false.")
885
2854
  },
886
2855
  annotations: { readOnlyHint: true }
887
2856
  },
@@ -911,15 +2880,15 @@ function registerHarnessIssueTools(server, session) {
911
2880
  {
912
2881
  description: HARNESS_TOOL_DESCRIPTIONS2.report_issue_verdicts,
913
2882
  inputSchema: {
914
- verdicts: z2.array(
915
- z2.object({
916
- ref: z2.string().regex(/^BW-[1-9]\d*$/).describe("The issue code, e.g. BW-17."),
917
- verdict: z2.enum(ISSUE_VERDICT_KINDS),
918
- reason: z2.enum(["incorrect", "handled_elsewhere", "intended"]).optional().describe("Only for not_a_bug."),
919
- note: z2.string().min(3).max(2e3).describe(
2883
+ verdicts: z4.array(
2884
+ z4.object({
2885
+ ref: z4.string().regex(/^BW-[1-9]\d*$/).describe("The issue code, e.g. BW-17."),
2886
+ verdict: z4.enum(ISSUE_VERDICT_KINDS),
2887
+ reason: z4.enum(["incorrect", "handled_elsewhere", "intended"]).optional().describe("Only for not_a_bug."),
2888
+ note: z4.string().min(3).max(2e3).describe(
920
2889
  "Your evidence in a sentence: a file:line, a test, the caller that handles it."
921
2890
  ),
922
- duplicateOf: z2.string().regex(/^BW-[1-9]\d*$/).optional().describe("Only for duplicate: the issue this one repeats.")
2891
+ duplicateOf: z4.string().regex(/^BW-[1-9]\d*$/).optional().describe("Only for duplicate: the issue this one repeats.")
923
2892
  })
924
2893
  ).min(1).max(MAX_APP_ISSUE_VERDICTS_PER_CALL)
925
2894
  }
@@ -959,7 +2928,7 @@ function registerHarnessPrompts(server, session) {
959
2928
  title: prompt.title,
960
2929
  description: prompt.description,
961
2930
  argsSchema: {
962
- count: z2.string().optional().describe(`How many issues to take on (default ${prompt.defaultCount}, at most 50).`)
2931
+ count: z4.string().optional().describe(`How many issues to take on (default ${prompt.defaultCount}, at most 50).`)
963
2932
  }
964
2933
  },
965
2934
  async (args) => {
@@ -1025,8 +2994,10 @@ function createHarnessServer(session) {
1025
2994
  { instructions: HARNESS_SERVER_INSTRUCTIONS }
1026
2995
  );
1027
2996
  registerHarnessTools(server, session);
2997
+ registerHarnessDocumentTools(server, session);
1028
2998
  registerHarnessIssueTools(server, session);
1029
2999
  registerHarnessPrompts(server, session);
3000
+ teachInvalidArguments(server);
1030
3001
  session.setRootsProvider(async () => {
1031
3002
  if (!server.server.getClientCapabilities()?.roots) return null;
1032
3003
  const { roots } = await server.server.listRoots(void 0, { timeout: ROOTS_TIMEOUT_MS });