@bendyline/gezel-mcp 1.0.2 → 1.0.4

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.d.ts CHANGED
@@ -18,7 +18,7 @@
18
18
  * whose names come from the applied type's manifest, not from this frozen
19
19
  * contract. Registration guards them against colliding with these names.
20
20
  */
21
- declare const ALWAYS_REGISTERED_TOOLS: readonly ["search_memory", "save_memory", "list_memories", "list_dir", "read_file", "read_files", "stat", "write_file", "append_to_file", "replace_in_file", "replace_lines", "apply_patch", "insert_at_marker", "delete_path", "make_dir", "rename", "copy_artifact_to_workspace", "validate", "npm_install", "list_package_scripts", "run_package_script", "run_npx", "run_nodejs_script", "derive_file", "list_packages", "run_playwright_script", "list_artifacts", "read_artifact", "write_artifact", "grep_artifact", "browser_find_page_element", "list_documents", "read_document", "write_document", "delete_document", "search_documents", "list_gezels", "create_gezel", "list_gilde", "list_project_types", "apply_project_type", "start_project_from_type", "export_project_type", "import_project_type", "ensure_gezel", "update_gezel", "message_gezel", "ask_gezel", "ask_specialist", "delegate_developer", "consult_developer", "delegate_designer", "consult_designer", "delegate_reviewer", "consult_reviewer", "delegate_planner", "consult_planner", "delegate_researcher", "consult_researcher", "delegate_builder", "consult_builder", "delegate_writer", "consult_writer", "delegate_image_generator", "consult_image_generator", "delegate_voorman", "consult_voorman", "delegate_meester", "consult_meester", "ask_user_question", "list_projects", "start_project", "fetch_repo", "fetch_diff", "update_project", "list_project_gezels", "add_gezel_to_project", "remove_gezel_from_project", "list_suggested_work", "enable_suggested_work", "disable_suggested_work", "list_tasks", "get_task", "create_task", "start_plan", "update_task", "set_outcomes", "verify_outcome", "add_verification_step", "spawn_task_instances", "list_task_children", "set_task_status", "activate_task", "assign_task", "add_task_step", "advance_task_step", "read_task_notes", "write_task_note", "search_history", "search_sessions", "how_do_i", "render_image", "generate_image", "describe_image", "read_image_metadata", "generate_video", "transcribe_audio", "synthesize_speech", "fetch_url", "web_search", "wikipedia_search", "grep_files", "find_files", "diff_files", "read_image_as_base64", "outline_file", "find_symbol", "read_symbol", "find_references", "map_repo", "search_code", "file_review", "list_file_issues", "get_file_issue", "set_file_issue_status", "security_scan", "security_overview", "scan_findings", "map_attack_surface", "list_dependencies", "trace_taint", "search_docs", "read_doc_as_markdown", "search_images", "find_similar_images", "describe_folder", "find_entity", "list_entity_mentions", "list_archive", "extract_archive", "run_git", "list_scripts", "run_installed_script", "get_script_run", "list_craftbooks", "suggest_craftbook", "invoke_craftbook", "import_skill", "craftbook_read", "craftbook_write", "craftbook_add_step", "set_step_deliverable", "craftbook_remove_step", "craftbook_reorder_steps", "craftbook_set_entry", "craftbook_update", "export_task_craftbook", "github_pr_list", "github_pr_view", "github_pr_files", "github_pr_diff", "github_pr_comments", "github_pr_comment", "github_pr_create", "github_workflow_runs", "github_check_status"];
21
+ declare const ALWAYS_REGISTERED_TOOLS: readonly ["search_memory", "save_memory", "list_memories", "list_dir", "read_file", "read_files", "stat", "write_file", "append_to_file", "replace_in_file", "replace_lines", "apply_patch", "insert_at_marker", "delete_path", "make_dir", "rename", "copy_artifact_to_workspace", "validate", "npm_install", "list_package_scripts", "run_package_script", "run_npx", "run_nodejs_script", "derive_file", "list_packages", "run_playwright_script", "list_artifacts", "read_artifact", "write_artifact", "grep_artifact", "browser_find_page_element", "list_documents", "read_document", "write_document", "delete_document", "search_documents", "list_gezels", "create_gezel", "list_gilde", "list_project_types", "apply_project_type", "start_project_from_type", "export_project_type", "import_project_type", "ensure_gezel", "update_gezel", "message_gezel", "ask_gezel", "ask_specialist", "delegate_developer", "consult_developer", "delegate_designer", "consult_designer", "delegate_reviewer", "consult_reviewer", "delegate_planner", "consult_planner", "delegate_researcher", "consult_researcher", "delegate_builder", "consult_builder", "delegate_writer", "consult_writer", "delegate_image_generator", "consult_image_generator", "delegate_voorman", "consult_voorman", "delegate_meester", "consult_meester", "ask_user_question", "list_projects", "start_project", "fetch_repo", "fetch_diff", "update_project", "list_project_gezels", "add_gezel_to_project", "remove_gezel_from_project", "list_suggested_work", "enable_suggested_work", "disable_suggested_work", "list_tasks", "get_task", "create_task", "start_plan", "update_task", "set_outcomes", "verify_outcome", "add_verification_step", "spawn_task_instances", "list_task_children", "set_task_status", "activate_task", "assign_task", "add_task_step", "advance_task_step", "read_task_notes", "write_task_note", "search_history", "search_sessions", "how_do_i", "render_image", "generate_image", "describe_image", "read_image_metadata", "generate_video", "transcribe_audio", "synthesize_speech", "fetch_url", "web_search", "wikipedia_search", "grep_files", "find_files", "diff_files", "read_image_as_base64", "outline_file", "find_symbol", "read_symbol", "find_references", "map_repo", "search_code", "file_review", "list_file_issues", "get_file_issue", "set_file_issue_status", "security_scan", "security_overview", "scan_findings", "map_attack_surface", "list_dependencies", "trace_taint", "search_docs", "read_doc_as_markdown", "search_images", "find_similar_images", "describe_folder", "find_entity", "list_entity_mentions", "list_archive", "extract_archive", "run_git", "list_scripts", "run_installed_script", "get_script_run", "list_craftbooks", "suggest_craftbook", "invoke_craftbook", "import_skill", "craftbook_read", "craftbook_write", "craftbook_add_step", "set_step_deliverable", "craftbook_remove_step", "craftbook_reorder_steps", "craftbook_set_entry", "craftbook_update", "export_task_craftbook", "github_pr_list", "github_pr_view", "github_pr_files", "github_pr_file", "github_pr_diff", "github_pr_comments", "github_pr_comment", "github_pr_create", "github_workflow_runs", "github_check_status"];
22
22
  /**
23
23
  * Tools registered only when their feature or session-context gate is set
24
24
  * in the env. Keep contextual/compatibility tools here so inventory users
package/dist/index.js CHANGED
@@ -192,6 +192,7 @@ var ALWAYS_REGISTERED_TOOLS = [
192
192
  "github_pr_list",
193
193
  "github_pr_view",
194
194
  "github_pr_files",
195
+ "github_pr_file",
195
196
  "github_pr_diff",
196
197
  "github_pr_comments",
197
198
  "github_pr_comment",
package/dist/server.d.ts CHANGED
@@ -15,6 +15,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
15
15
  * GEZEL_PROJECT_ID — the project context
16
16
  * GEZEL_SESSION_ID — the chat session this subprocess serves
17
17
  * GEZEL_HOME — path to ~/.gezel (for direct memory access)
18
+ * GEZEL_ROLE_BASED_NAME_ONLY_MODE — 1/0 naming presentation inherited by new tasks
18
19
  * GEZEL_CRAFTBOOK_ID — explicit craftbook-editor context (loads step surgery)
19
20
  * GEZEL_MCP_LEGACY_TOOLS=1 — expose compatibility aliases during migration
20
21
  */
package/dist/server.js CHANGED
@@ -46,6 +46,59 @@ function commandResultIsError(result) {
46
46
  return !result.ok && result.approvalPending !== true;
47
47
  }
48
48
 
49
+ // src/craftbook-invocation-idempotency.ts
50
+ import { createHash } from "crypto";
51
+ function rootTurnIdFromMessages(sessionId2, messages) {
52
+ for (let index = messages.length - 1; index >= 0; index -= 1) {
53
+ const message = messages[index];
54
+ if (message?.role === "user") return `${sessionId2}:${index}:${message.at}`;
55
+ }
56
+ return null;
57
+ }
58
+ function canonicalize(value) {
59
+ if (Array.isArray(value)) return value.map(canonicalize);
60
+ if (value && typeof value === "object") {
61
+ return Object.fromEntries(
62
+ Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => [key, canonicalize(entry)])
63
+ );
64
+ }
65
+ return value;
66
+ }
67
+ function invocationSignature(invocation) {
68
+ return JSON.stringify(canonicalize(invocation));
69
+ }
70
+ function rootTurnInvocationKey(rootTurnId, invocation) {
71
+ return `craftbook-root-v1:${createHash("sha256").update(rootTurnId).update("\n").update(invocationSignature(invocation)).digest("hex")}`;
72
+ }
73
+ var RootTurnInvocationCache = class {
74
+ constructor(maxEntries = 128) {
75
+ this.maxEntries = maxEntries;
76
+ }
77
+ maxEntries;
78
+ entries = /* @__PURE__ */ new Map();
79
+ async run(args) {
80
+ const key = `${args.rootTurnId}
81
+ ${invocationSignature(args.invocation)}`;
82
+ const existing = this.entries.get(key);
83
+ if (existing) return { value: await existing, reused: true };
84
+ const pending = args.execute();
85
+ this.entries.set(key, pending);
86
+ while (this.entries.size > this.maxEntries) {
87
+ const oldest = this.entries.keys().next().value;
88
+ if (oldest === void 0) break;
89
+ this.entries.delete(oldest);
90
+ }
91
+ try {
92
+ const value = await pending;
93
+ if (args.cacheResult && !args.cacheResult(value)) this.entries.delete(key);
94
+ return { value, reused: false };
95
+ } catch (error) {
96
+ this.entries.delete(key);
97
+ throw error;
98
+ }
99
+ }
100
+ };
101
+
49
102
  // src/craftbook-routing.ts
50
103
  import { z as z2 } from "zod";
51
104
 
@@ -776,6 +829,7 @@ var ALWAYS_REGISTERED_TOOLS = [
776
829
  "github_pr_list",
777
830
  "github_pr_view",
778
831
  "github_pr_files",
832
+ "github_pr_file",
779
833
  "github_pr_diff",
780
834
  "github_pr_comments",
781
835
  "github_pr_comment",
@@ -1059,7 +1113,8 @@ var GitToolOutputSchema = ExecutionToolOutputSchema.extend({
1059
1113
  });
1060
1114
  var MemorySaveToolOutputSchema = ToolResultSummarySchema.extend({
1061
1115
  status: z3.enum(["saved", "duplicate"]),
1062
- scope: z3.enum(["gezel", "project"])
1116
+ scope: z3.enum(["gezel", "project"]),
1117
+ indexed: z3.boolean().optional()
1063
1118
  });
1064
1119
  var MemoryListToolOutputSchema = ToolResultSummarySchema.extend({
1065
1120
  scope: z3.enum(["gezel", "project"]),
@@ -1247,6 +1302,7 @@ var READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
1247
1302
  "github_pr_list",
1248
1303
  "github_pr_view",
1249
1304
  "github_pr_files",
1305
+ "github_pr_file",
1250
1306
  "github_pr_diff",
1251
1307
  "github_pr_comments",
1252
1308
  "github_workflow_runs",
@@ -1348,6 +1404,7 @@ var OPEN_WORLD_TOOLS = /* @__PURE__ */ new Set([
1348
1404
  "github_pr_list",
1349
1405
  "github_pr_view",
1350
1406
  "github_pr_files",
1407
+ "github_pr_file",
1351
1408
  "github_pr_diff",
1352
1409
  "github_pr_comments",
1353
1410
  "github_pr_comment",
@@ -2694,6 +2751,8 @@ var gezelId = process.env.GEZEL_AGENT_ID ?? "";
2694
2751
  var projectId = process.env.GEZEL_PROJECT_ID ?? "default";
2695
2752
  var sessionId = process.env.GEZEL_SESSION_ID ?? "";
2696
2753
  var sessionStepId = process.env.GEZEL_STEP_ID ?? "";
2754
+ var sessionRoleBasedNameOnlyMode = process.env.GEZEL_ROLE_BASED_NAME_ONLY_MODE === "1" ? true : process.env.GEZEL_ROLE_BASED_NAME_ONLY_MODE === "0" ? false : void 0;
2755
+ var sessionTaskNamingMode = sessionRoleBasedNameOnlyMode === void 0 ? {} : { roleBasedNameOnlyMode: sessionRoleBasedNameOnlyMode };
2697
2756
  var sessionTaskRef = process.env.GEZEL_TASK_REF ?? "";
2698
2757
  var sessionCraftbookId = process.env.GEZEL_CRAFTBOOK_ID ?? "";
2699
2758
  var certPath = process.env.GEZEL_CERT_PATH;
@@ -2813,7 +2872,8 @@ server.tool(
2813
2872
  }
2814
2873
  const data = await res.json();
2815
2874
  const results = data.results ?? [];
2816
- const summary = results.length ? `Found ${results.length} relevant ${results.length === 1 ? "memory" : "memories"}.` : "No relevant memories found.";
2875
+ const resultSummary = results.length ? `Found ${results.length} relevant ${results.length === 1 ? "memory" : "memories"}.` : "No relevant memories found.";
2876
+ const summary = data.degraded?.message ? `${data.degraded.message} ${resultSummary}` : resultSummary;
2817
2877
  const formatted = results.map((r) => `[${r.scope}/${r.day} score=${r.score.toFixed(2)}] ${r.text}`).join("\n\n");
2818
2878
  return okResult(
2819
2879
  SearchToolOutputSchema,
@@ -2822,7 +2882,9 @@ server.tool(
2822
2882
  query,
2823
2883
  matches: results,
2824
2884
  count: results.length,
2825
- truncated: false
2885
+ truncated: false,
2886
+ ...data.mode ? { mode: data.degraded ? `${data.mode}-fallback` : data.mode } : {},
2887
+ engine: data.mode === "semantic" || data.mode === "hybrid" ? "sqlite-vec" : "markdown"
2826
2888
  },
2827
2889
  { text: formatted ? `${summary}
2828
2890
  ${formatted}` : summary }
@@ -2864,8 +2926,19 @@ server.tool(
2864
2926
  }
2865
2927
  const data = await res.json().catch(() => ({}));
2866
2928
  const status = data.status === "duplicate" ? "duplicate" : "saved";
2867
- const summary = status === "duplicate" ? `Memory already existed (${scope}); no duplicate was added.` : `Memory saved (${scope}).`;
2868
- return okResult(MemorySaveToolOutputSchema, { summary, status, scope }, { text: summary });
2929
+ const savedSummary = status === "duplicate" ? `Memory already existed (${scope}); no duplicate was added.` : `Memory saved (${scope}).`;
2930
+ const degradedMessage = data.degraded && typeof data.degraded.message === "string" ? data.degraded.message : void 0;
2931
+ const summary = degradedMessage ? `${savedSummary} ${degradedMessage}` : savedSummary;
2932
+ return okResult(
2933
+ MemorySaveToolOutputSchema,
2934
+ {
2935
+ summary,
2936
+ status,
2937
+ scope,
2938
+ ...typeof data.indexed === "boolean" ? { indexed: data.indexed } : {}
2939
+ },
2940
+ { text: summary }
2941
+ );
2869
2942
  } catch (err) {
2870
2943
  return errorResult(`save_memory failed: ${unwrapApiError(err)}`);
2871
2944
  }
@@ -3256,7 +3329,7 @@ ${listing}` : summary }
3256
3329
  );
3257
3330
  server.tool(
3258
3331
  "read_file",
3259
- "Read one workspace file, optionally only an inclusive line range. For files over ~200 lines, pass `startLine`/`endLine` from grep_files, outline_file, or an error instead of loading the whole file. Omit both range fields for the backward-compatible full read. Output uses `N\u2192` line gutters for precise edits; the gutter is display-only and is never part of the file. Pass `raw: true` for text without gutters.",
3332
+ "Read one project-workspace file, optionally only an inclusive line range. This tool never reads the separate artifacts drawer; use read_artifact for artifact inputs. For files over ~200 lines, pass `startLine`/`endLine` from grep_files, outline_file, or an error instead of loading the whole file. Omit both range fields for the backward-compatible full read. Output uses `N\u2192` line gutters for precise edits; the gutter is display-only and is never part of the file. Pass `raw: true` for text without gutters.",
3260
3333
  {
3261
3334
  path: z5.string().min(1).max(4096).describe("File path relative to the project root."),
3262
3335
  startLine: z5.number().int().min(1).max(1e7).optional().describe("1-based first line to return (inclusive). Defaults to 1."),
@@ -3301,6 +3374,11 @@ server.tool(
3301
3374
  const base = unwrapApiError(err);
3302
3375
  let text = `read_file "${path}": ${base}`;
3303
3376
  if (/not found|404|no such file/i.test(base)) {
3377
+ const artifactCollision = await artifactCollisionForWorkspacePath(path);
3378
+ if (artifactCollision) {
3379
+ text += `. A project artifact exists at "${artifactCollision}". The workspace and artifacts are separate drawers; call read_artifact({ path: ${JSON.stringify(artifactCollision)} }) instead of read_file. The artifact was not opened automatically.`;
3380
+ return { content: [{ type: "text", text }], isError: true };
3381
+ }
3304
3382
  try {
3305
3383
  const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
3306
3384
  const listing = await api.listProjectWorkspace(projectId, dir, false);
@@ -4664,8 +4742,13 @@ async function responseErrorMessage(res) {
4664
4742
  if (body) {
4665
4743
  try {
4666
4744
  const parsed = JSON.parse(body);
4667
- if (typeof parsed.error === "string" && parsed.error) return parsed.error;
4668
- if (typeof parsed.message === "string" && parsed.message) return parsed.message;
4745
+ const requestSuffix = typeof parsed.requestId === "string" && parsed.requestId ? ` (request id: ${parsed.requestId})` : "";
4746
+ if (typeof parsed.error === "string" && parsed.error) {
4747
+ return `${parsed.error}${requestSuffix}`;
4748
+ }
4749
+ if (typeof parsed.message === "string" && parsed.message) {
4750
+ return `${parsed.message}${requestSuffix}`;
4751
+ }
4669
4752
  } catch {
4670
4753
  }
4671
4754
  return body.length > 1e3 ? `${body.slice(0, 1e3)}\u2026` : body;
@@ -4896,6 +4979,15 @@ async function workspaceCollisionForArtifactPath(cleanPath) {
4896
4979
  }
4897
4980
  return null;
4898
4981
  }
4982
+ async function artifactCollisionForWorkspacePath(path) {
4983
+ try {
4984
+ const cleanPath = normalizeArtifactPath(path);
4985
+ const result = await api.readProjectArtifactSlice(projectId, cleanPath, { head: 0 });
4986
+ return result.kind === "found" && !result.fuzzy ? result.path : null;
4987
+ } catch {
4988
+ return null;
4989
+ }
4990
+ }
4899
4991
  var WORKSPACE_DELIVERABLE_EXTENSIONS = /* @__PURE__ */ new Set([
4900
4992
  "html",
4901
4993
  "htm",
@@ -5955,6 +6047,16 @@ async function requestCraftbookToolsetInstalls(project, craftbookId, requirement
5955
6047
  }
5956
6048
  return installed;
5957
6049
  }
6050
+ var invokeCraftbookRootTurnCache = new RootTurnInvocationCache();
6051
+ async function currentRootTurnId() {
6052
+ if (!sessionId) return null;
6053
+ try {
6054
+ const session = await api.getChatSession(sessionId);
6055
+ return rootTurnIdFromMessages(sessionId, session.messages);
6056
+ } catch {
6057
+ return null;
6058
+ }
6059
+ }
5958
6060
  async function launchCraftbookTask(args) {
5959
6061
  let projectCraftbooks = await api.listProjectCraftbooks(args.project);
5960
6062
  let missing = projectCraftbooks.missingToolsets[args.craftbookId] ?? [];
@@ -5987,12 +6089,14 @@ async function launchCraftbookTask(args) {
5987
6089
  }
5988
6090
  const craftbookName = projectCraftbooks.items.find((item) => item.manifest.id === args.craftbookId)?.manifest.name ?? args.craftbookId;
5989
6091
  const task = await api.createTask(args.project, {
6092
+ ...sessionTaskNamingMode,
5990
6093
  title: args.title ?? craftbookName,
5991
6094
  description: normalizedCraftbookTaskDescription(args.description, args.craftbookId),
5992
6095
  craftbookId: args.craftbookId,
5993
6096
  ...args.version ? { craftbookVersion: args.version } : {},
5994
6097
  ...args.params && Object.keys(args.params).length > 0 ? { craftbookParams: args.params } : {},
5995
6098
  ...args.assignee ? { assignee: assigneeFromArg(args.assignee) } : {},
6099
+ ...args.craftbookInvocationKey ? { craftbookInvocationKey: args.craftbookInvocationKey } : {},
5996
6100
  ...gezelId ? { createdBy: { kind: "gezel", gezelId } } : {},
5997
6101
  dispatchEntry: true
5998
6102
  });
@@ -6215,7 +6319,7 @@ server.tool(
6215
6319
  const resolvedProject = project ? await resolveProjectId(project) : projectId;
6216
6320
  try {
6217
6321
  const invocationParams = normalizeCraftbookInvocationParams(params, outputPath);
6218
- const launch = await launchCraftbookTask({
6322
+ const invocation = {
6219
6323
  craftbookId,
6220
6324
  project: resolvedProject,
6221
6325
  title,
@@ -6223,7 +6327,19 @@ server.tool(
6223
6327
  version,
6224
6328
  assignee,
6225
6329
  params: invocationParams
6226
- });
6330
+ };
6331
+ const rootTurnId = await currentRootTurnId();
6332
+ const launchInvocation = rootTurnId ? {
6333
+ ...invocation,
6334
+ craftbookInvocationKey: rootTurnInvocationKey(rootTurnId, invocation)
6335
+ } : invocation;
6336
+ const launched = rootTurnId ? await invokeCraftbookRootTurnCache.run({
6337
+ rootTurnId,
6338
+ invocation,
6339
+ execute: () => launchCraftbookTask(launchInvocation),
6340
+ cacheResult: (result) => result.kind !== "setup-required"
6341
+ }) : { value: await launchCraftbookTask(launchInvocation), reused: false };
6342
+ const launch = launched.value;
6227
6343
  if (launch.kind === "setup-required") {
6228
6344
  return {
6229
6345
  content: [
@@ -6238,11 +6354,12 @@ server.tool(
6238
6354
  const created = launch.task;
6239
6355
  const stepCount = created.craftbook.steps.length;
6240
6356
  const installedText = launch.installed.length > 0 ? ` Installed or upgraded project toolset${launch.installed.length === 1 ? "" : "s"}: ${launch.installed.join(", ")}.` : "";
6357
+ const idempotentText = launched.reused ? " This identical craftbook invocation already succeeded in the current root turn; reused its task instead of creating a duplicate." : "";
6241
6358
  return {
6242
6359
  content: [
6243
6360
  {
6244
6361
  type: "text",
6245
- text: `Invoked craftbook "${craftbookId}" \u2014 task ${created.ref} (${stepCount} step(s)). Active step ${created.activeStepId ?? "(none)"} was dispatched to the recipe-selected specialist.${installedText}`
6362
+ text: `Invoked craftbook "${craftbookId}" \u2014 task ${created.ref} (${stepCount} step(s)). Active step ${created.activeStepId ?? "(none)"} was dispatched to the recipe-selected specialist.${installedText}${idempotentText}`
6246
6363
  }
6247
6364
  ]
6248
6365
  };
@@ -7606,7 +7723,7 @@ function normalizeSpecialistRole(value) {
7606
7723
  }
7607
7724
  const resolved = resolveRoleId(lower) ?? resolveRoleId(normalized);
7608
7725
  if (resolved && resolved !== "meester" && resolved !== "voorman") return resolved;
7609
- return "developer";
7726
+ return "builder";
7610
7727
  }
7611
7728
  function repoFetchRedirectForMacro(input) {
7612
7729
  const text = `${input.name}
@@ -7902,6 +8019,7 @@ ${idempotent.resultText}`
7902
8019
  `${brief.name} ${brief.about ?? ""} ${brief.taskDescription ?? ""} ${effectiveTaskDescription}`
7903
8020
  ) : null;
7904
8021
  const task = crewLoop ? await api.createTask(project.id, {
8022
+ ...sessionTaskNamingMode,
7905
8023
  title: input.taskTitle ?? `Build ${brief.name}`,
7906
8024
  description: effectiveTaskDescription,
7907
8025
  assignee: { kind: "gezel", gezelId: voorman.id },
@@ -7909,6 +8027,7 @@ ${idempotent.resultText}`
7909
8027
  entryStepId: crewLoop.entryStepId,
7910
8028
  dispatchEntry: true
7911
8029
  }) : await api.createTask(project.id, {
8030
+ ...sessionTaskNamingMode,
7912
8031
  title: input.taskTitle ?? `Build ${brief.name}`,
7913
8032
  description: effectiveTaskDescription,
7914
8033
  assignee: { kind: "gezel", gezelId: voorman.id },
@@ -8026,6 +8145,7 @@ ${idempotent.resultText}`
8026
8145
  `${brief.name} ${brief.about} ${brief.taskDescription ?? ""} ${effectiveTaskDescription}`
8027
8146
  ) : null;
8028
8147
  const task = crewLoop ? await api.createTask(project.id, {
8148
+ ...sessionTaskNamingMode,
8029
8149
  title: taskTitle ?? `Build ${brief.name}`,
8030
8150
  description: effectiveTaskDescription,
8031
8151
  assignee: { kind: "gezel", gezelId: voorman.id },
@@ -8033,6 +8153,7 @@ ${idempotent.resultText}`
8033
8153
  entryStepId: crewLoop.entryStepId,
8034
8154
  dispatchEntry: true
8035
8155
  }) : await api.createTask(project.id, {
8156
+ ...sessionTaskNamingMode,
8036
8157
  title: taskTitle ?? `Build ${brief.name}`,
8037
8158
  description: effectiveTaskDescription,
8038
8159
  assignee: { kind: "gezel", gezelId: voorman.id },
@@ -8140,11 +8261,11 @@ ${idempotent.resultText}`
8140
8261
  mode: "solo"
8141
8262
  });
8142
8263
  const { name: gezelName, gender: gezelGender } = pickRandomNameWithGender();
8143
- const ambachtsman = await api.createGezelFromTemplate(effectiveSpecialistRole, {
8264
+ const builder = await api.createGezelFromTemplate(effectiveSpecialistRole, {
8144
8265
  name: gezelName,
8145
8266
  gender: gezelGender
8146
8267
  });
8147
- await api.updateProject(project.id, { voormanGezelId: ambachtsman.id });
8268
+ await api.updateProject(project.id, { voormanGezelId: builder.id });
8148
8269
  const effectiveTaskDescription = buildKickoffTaskDescription({
8149
8270
  ...brief,
8150
8271
  ...kickoffMessage ? { kickoffNote: kickoffMessage } : {}
@@ -8155,21 +8276,23 @@ ${idempotent.resultText}`
8155
8276
  });
8156
8277
  const craftbookPick = await pickCraftbookForBrief(project.id, brief);
8157
8278
  const soloLoop = craftbookPick ? await buildSoloLoopSteps(
8158
- ambachtsman.id,
8279
+ builder.id,
8159
8280
  sourceDeliverablePath ?? "index.html",
8160
8281
  `${brief.name} ${brief.about} ${brief.taskDescription ?? ""} ${effectiveTaskDescription}`
8161
8282
  ) : null;
8162
8283
  const task = soloLoop ? await api.createTask(project.id, {
8284
+ ...sessionTaskNamingMode,
8163
8285
  title: taskTitle ?? `Build ${brief.name}`,
8164
8286
  description: effectiveTaskDescription,
8165
- assignee: { kind: "gezel", gezelId: ambachtsman.id },
8287
+ assignee: { kind: "gezel", gezelId: builder.id },
8166
8288
  steps: soloLoop.steps,
8167
8289
  entryStepId: soloLoop.entryStepId,
8168
8290
  dispatchEntry: true
8169
8291
  }) : await api.createTask(project.id, {
8292
+ ...sessionTaskNamingMode,
8170
8293
  title: taskTitle ?? `Build ${brief.name}`,
8171
8294
  description: effectiveTaskDescription,
8172
- assignee: { kind: "gezel", gezelId: ambachtsman.id },
8295
+ assignee: { kind: "gezel", gezelId: builder.id },
8173
8296
  steps: [
8174
8297
  {
8175
8298
  name: "Plan and execute",
@@ -8179,7 +8302,7 @@ ${idempotent.resultText}`
8179
8302
  ],
8180
8303
  dispatchEntry: true
8181
8304
  });
8182
- const resultText = `Started project "${brief.name}" (${project.id}). Recruited ${ambachtsman.name} as lead (template: ${effectiveSpecialistRole}). Created task ${task.ref} ("${task.title}") and handed ${ambachtsman.name} its entry step \u2014 they are starting now in a task-scoped session. No reply lands in this thread; progress accrues on the task (notes, gates, status \u2014 get_task / read_task_notes when the user asks). Tell the user ${ambachtsman.name} is on it and they can watch the work in the ${brief.name} project.`;
8305
+ const resultText = `Started project "${brief.name}" (${project.id}). Recruited ${builder.name} as lead (template: ${effectiveSpecialistRole}). Created task ${task.ref} ("${task.title}") and handed ${builder.name} its entry step \u2014 they are starting now in a task-scoped session. No reply lands in this thread; progress accrues on the task (notes, gates, status \u2014 get_task / read_task_notes when the user asks). Tell the user ${builder.name} is on it and they can watch the work in the ${brief.name} project.`;
8183
8306
  recordMacroResult(cacheTool, brief.name, project.id, resultText);
8184
8307
  return {
8185
8308
  content: [
@@ -8646,6 +8769,7 @@ server.tool(
8646
8769
  try {
8647
8770
  const projectId2 = await resolveProjectId(project);
8648
8771
  const created = await api.createTask(projectId2, {
8772
+ ...sessionTaskNamingMode,
8649
8773
  title,
8650
8774
  description,
8651
8775
  ...plan ? { plan } : {},
@@ -8708,6 +8832,7 @@ server.tool(
8708
8832
  const resolvedProject = project ? await resolveProjectId(project) : projectId;
8709
8833
  const assignee = gezelId ? { kind: "gezel", gezelId } : { kind: "user" };
8710
8834
  const draft = await api.createTask(resolvedProject, {
8835
+ ...sessionTaskNamingMode,
8711
8836
  title: title ?? `Plan: ${goal.slice(0, 60)}`,
8712
8837
  description: `DRAFT PLAN (being authored). User goal: ${goal}`.padEnd(40, " "),
8713
8838
  status: "draft",
@@ -8720,6 +8845,7 @@ server.tool(
8720
8845
  ]
8721
8846
  });
8722
8847
  const authoring = await api.createTask(resolvedProject, {
8848
+ ...sessionTaskNamingMode,
8723
8849
  title: `Author plan for ${draft.ref}`,
8724
8850
  description: `Run the plan craftbook to author task ${draft.ref}. User goal: ${goal}`,
8725
8851
  craftbookId: "plan",
@@ -9277,14 +9403,14 @@ ${pausedNote}`,
9277
9403
  );
9278
9404
  server.tool(
9279
9405
  "read_task_notes",
9280
- "Read the chronological feed of timestamped notes for a task (or a specific step). Each entry has an author (a gezel or the user) and was appended at a known time \u2014 newest first.",
9406
+ "Read the chronological feed of timestamped notes for a task (or a specific step). Omit stepId to read the whole task feed across every step. Each entry has an author (a gezel or the user) and was appended at a known time \u2014 newest first.",
9281
9407
  {
9282
9408
  ref: z5.string(),
9283
9409
  stepId: z5.string().optional()
9284
9410
  },
9285
9411
  async ({ ref, stepId }) => {
9286
9412
  const parsed = parseRef(ref);
9287
- const effectiveStep = stepId ?? (sessionStepId || void 0);
9413
+ const effectiveStep = stepId?.trim() || void 0;
9288
9414
  const { notes } = await api.listTaskNotes(parsed.projectId, parsed.num, effectiveStep);
9289
9415
  const summary = `Loaded ${notes.length} ${notes.length === 1 ? "note" : "notes"} for ${ref}${effectiveStep ? `/${effectiveStep}` : ""}.`;
9290
9416
  return okResult(
@@ -11246,26 +11372,57 @@ server.tool(
11246
11372
  );
11247
11373
  server.tool(
11248
11374
  "github_pr_files",
11249
- "List the files changed in a PR with per-file additions, deletions, and a truncated patch hunk. Use this when you want a structured per-file view; for the full unified diff use github_pr_diff.",
11375
+ "List a bounded page of files changed in a PR. Defaults to compact metadata only so filenames later in a large PR are never hidden behind early patch bodies. Follow `nextOffset` until `hasMore: false`; set includePatch only for a small page, or use github_pr_file for one path.",
11250
11376
  {
11251
11377
  project: z5.string().optional(),
11252
- number: z5.number().int().positive()
11378
+ number: z5.number().int().positive(),
11379
+ offset: z5.number().int().nonnegative().optional().describe("Zero-based file offset (default 0)."),
11380
+ limit: z5.number().int().min(1).max(200).optional().describe("Files per page (default 100)."),
11381
+ paths: z5.array(z5.string().min(1)).max(50).optional().describe("Optional exact changed paths to select."),
11382
+ includePatch: z5.boolean().optional().describe("Include bounded patches for this page. Defaults false.")
11253
11383
  },
11254
- async ({ project, number }) => {
11384
+ async ({ project, number, offset, limit, paths, includePatch }) => {
11255
11385
  const resolved = project ? await resolveProjectId(project) : projectId;
11256
11386
  try {
11257
- const res = await api.listProjectGitHubPullFiles(resolved, number);
11387
+ const res = await api.listProjectGitHubPullFiles(resolved, number, {
11388
+ ...offset !== void 0 ? { offset } : {},
11389
+ ...limit !== void 0 ? { limit } : {},
11390
+ ...paths ? { paths } : {},
11391
+ includePatch: includePatch === true
11392
+ });
11258
11393
  if (!res.files.length) {
11259
- return { content: [{ type: "text", text: "No file changes in this PR." }] };
11394
+ return {
11395
+ content: [
11396
+ {
11397
+ type: "text",
11398
+ text: paths?.length ? `No changed files matched: ${paths.join(", ")}` : "No file changes in this PR."
11399
+ }
11400
+ ]
11401
+ };
11260
11402
  }
11261
11403
  const blocks = res.files.map((f) => {
11262
11404
  const header = `${f.filename} \u2014 ${f.status} (+${f.additions} \u2212${f.deletions})`;
11263
- return f.patch ? `${header}
11405
+ if (!f.patch) return header;
11406
+ const truncation = f.patchTruncated ? `
11407
+ [patch truncated: returned ${f.patch.length} of ${f.patchChars ?? "?"} chars; call github_pr_diff with path="${f.filename}" and nextOffset until complete]` : "";
11408
+ return `${header}
11264
11409
  \`\`\`diff
11265
11410
  ${f.patch}
11266
- \`\`\`` : header;
11411
+ \`\`\`${truncation}`;
11267
11412
  });
11268
- return { content: [{ type: "text", text: blocks.join("\n\n") }] };
11413
+ const start = res.offset ?? offset ?? 0;
11414
+ const total = res.totalFiles ?? res.files.length;
11415
+ const end = start + res.files.length;
11416
+ const coverage = [
11417
+ `Coverage: files ${start + 1}-${end} of ${total}${res.allFiles !== void 0 && res.allFiles !== total ? ` selected from ${res.allFiles} PR files` : ""}.`,
11418
+ `Patches: ${res.includesPatch ? "included where available" : "omitted (metadata-only)"}.`,
11419
+ res.hasMore ? `hasMore: true; nextOffset: ${res.nextOffset ?? end}. Call github_pr_files again with that offset.` : "hasMore: false; this selection is complete."
11420
+ ].join("\n");
11421
+ return {
11422
+ content: [{ type: "text", text: `${coverage}
11423
+
11424
+ ${blocks.join("\n\n")}` }]
11425
+ };
11269
11426
  } catch (err) {
11270
11427
  const msg = unwrapApiError(err);
11271
11428
  return {
@@ -11275,18 +11432,79 @@ ${f.patch}
11275
11432
  }
11276
11433
  }
11277
11434
  );
11435
+ server.tool(
11436
+ "github_pr_file",
11437
+ "Fetch one changed path and its bounded patch. Use this after github_pr_files identifies a file; if the patch is truncated, continue with github_pr_diff({ number, path, offset: nextOffset }).",
11438
+ {
11439
+ project: z5.string().optional(),
11440
+ number: z5.number().int().positive(),
11441
+ path: z5.string().min(1).describe("Exact changed path from github_pr_files.")
11442
+ },
11443
+ async ({ project, number, path }) => {
11444
+ const resolved = project ? await resolveProjectId(project) : projectId;
11445
+ try {
11446
+ const res = await api.listProjectGitHubPullFiles(resolved, number, {
11447
+ paths: [path],
11448
+ limit: 1,
11449
+ includePatch: true
11450
+ });
11451
+ const file = res.files[0];
11452
+ if (!file) {
11453
+ return {
11454
+ content: [{ type: "text", text: `Changed path not found: ${path}` }],
11455
+ isError: true
11456
+ };
11457
+ }
11458
+ const header = `${file.filename} \u2014 ${file.status} (+${file.additions} \u2212${file.deletions})`;
11459
+ const patch = file.patch ? `
11460
+
11461
+ \`\`\`diff
11462
+ ${file.patch}
11463
+ \`\`\`` : "\n\n(No patch returned.)";
11464
+ const truncation = file.patchTruncated ? `
11465
+
11466
+ Patch truncated: returned ${file.patch?.length ?? 0} of ${file.patchChars ?? "?"} chars. Call github_pr_diff({ number: ${number}, path: ${JSON.stringify(file.filename)} }) and follow nextOffset.` : "";
11467
+ return { content: [{ type: "text", text: `${header}${patch}${truncation}` }] };
11468
+ } catch (err) {
11469
+ const msg = unwrapApiError(err);
11470
+ return {
11471
+ content: [{ type: "text", text: `github_pr_file failed: ${msg}` }],
11472
+ isError: true
11473
+ };
11474
+ }
11475
+ }
11476
+ );
11278
11477
  server.tool(
11279
11478
  "github_pr_diff",
11280
- "Fetch the full unified diff for a PR (truncated at ~64KB). Use this to feed the diff body to the model when you want it to reason about changes holistically; for per-file iteration use github_pr_files.",
11479
+ "Fetch one explicit character page of a PR diff, optionally scoped to an exact changed path. The result always reports totalChars, truncated, and nextOffset; continue until truncated is false. For large PR discovery, page github_pr_files first instead of assuming one diff call is complete.",
11281
11480
  {
11282
11481
  project: z5.string().optional(),
11283
- number: z5.number().int().positive()
11482
+ number: z5.number().int().positive(),
11483
+ path: z5.string().min(1).optional().describe("Optional exact changed path."),
11484
+ offset: z5.number().int().nonnegative().optional().describe("Character offset (default 0)."),
11485
+ limit: z5.number().int().min(1).max(6e4).optional().describe("Characters to return (default 48,000; max 60,000).")
11284
11486
  },
11285
- async ({ project, number }) => {
11487
+ async ({ project, number, path, offset, limit }) => {
11286
11488
  const resolved = project ? await resolveProjectId(project) : projectId;
11287
11489
  try {
11288
- const res = await api.getProjectGitHubPullDiff(resolved, number);
11289
- return { content: [{ type: "text", text: res.diff || "(empty diff)" }] };
11490
+ const res = await api.getProjectGitHubPullDiff(resolved, number, {
11491
+ ...path ? { path } : {},
11492
+ ...offset !== void 0 ? { offset } : {},
11493
+ ...limit !== void 0 ? { limit } : {}
11494
+ });
11495
+ const scope = res.path ? ` for ${res.path}` : "";
11496
+ const start = res.offset ?? offset ?? 0;
11497
+ const returned = res.returnedChars ?? res.diff.length;
11498
+ const total = res.totalChars ?? res.diff.length;
11499
+ const meta = [
11500
+ `Diff page${scope}: chars ${start}-${start + returned} of ${total}.`,
11501
+ res.truncated ? `truncated: true; nextOffset: ${res.nextOffset ?? start + returned}. Continue with the same path and that offset.` : "truncated: false; this diff selection is complete."
11502
+ ].join("\n");
11503
+ return {
11504
+ content: [{ type: "text", text: `${meta}
11505
+
11506
+ ${res.diff || "(empty diff)"}` }]
11507
+ };
11290
11508
  } catch (err) {
11291
11509
  const msg = unwrapApiError(err);
11292
11510
  return {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-mcp",
3
- "version": "1.0.2",
3
+ "version": "1.0.4",
4
4
  "description": "Gezel MCP server — gives agents access to memory, workspace, artifacts, and tools.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -55,8 +55,8 @@
55
55
  "!dist/**/*.map"
56
56
  ],
57
57
  "dependencies": {
58
- "@bendyline/gezel": "1.0.2",
59
- "@bendyline/gezel-client": "1.0.2",
58
+ "@bendyline/gezel": "1.0.4",
59
+ "@bendyline/gezel-client": "1.0.4",
60
60
  "@modelcontextprotocol/sdk": "^1.29.0",
61
61
  "typescript": "^6.0.3",
62
62
  "zod": "^4.4.3"