@trainheroic-unofficial/core 3.2.0 → 3.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -8,6 +8,12 @@ declare const idParam: import("zod").ZodUnion<readonly [import("zod").ZodNumber,
8
8
  declare function toId(value: string | number): number;
9
9
  declare const READ: {
10
10
  readonly readOnlyHint: true;
11
+ readonly destructiveHint: false;
12
+ readonly openWorldHint: true;
13
+ };
14
+ declare const ADDITIVE: {
15
+ readonly readOnlyHint: false;
16
+ readonly destructiveHint: false;
11
17
  readonly openWorldHint: true;
12
18
  };
13
19
  declare const SYNC: {
@@ -36,13 +42,14 @@ declare function attempt<T extends ToolHandlerResult>(fn: () => Promise<T>): Pro
36
42
  declare const DEFAULT_RESULT_BUDGET = 60000;
37
43
  /**
38
44
  * Clip an array to its first `keep` items and attach the `__truncated` marker describing what was
39
- * dropped. The marker is model-facing (tools instruct the model to key off `__truncated`), so its
40
- * shape has exactly one definition here: the size-budget path (`boundedSerialize`) and any tool
41
- * that deliberately caps a list (e.g. `athlete_exercises`) emit the same thing.
45
+ * dropped. Every budget fallback that trims a list uses this envelope (`{ items, __truncated }`),
46
+ * including in-place object-array truncation (the sliced array becomes `items` and `field` names
47
+ * the original key). `athlete_exercises` uses the same helper for a client-side catalog cap.
42
48
  */
43
- declare function clipArray<T>(items: readonly T[], keep: number, hint?: string): {
49
+ declare function clipArray<T>(items: readonly T[], keep: number, hint?: string, field?: string): {
44
50
  items: T[];
45
51
  __truncated: {
52
+ field?: string;
46
53
  returned: number;
47
54
  total: number;
48
55
  omitted: number;
@@ -52,10 +59,8 @@ declare function clipArray<T>(items: readonly T[], keep: number, hint?: string):
52
59
  /** Active budget. Overridable via TH_MCP_RESULT_BUDGET on Node; the default on workerd. */
53
60
  declare function resultBudget(): number;
54
61
  /**
55
- * Serialize `data` as JSON within `budget` characters. Small results are pretty-printed.
56
- * Oversized results degrade in order: trim a top-level array (wrapping it as
57
- * `{ items, __truncated }`), then a top-level object's largest array property (annotated
58
- * with `__truncated`), then a last-resort hard character cap. Pure and side-effect free.
62
+ * Serialize `data` within `budget` characters. Small JSON results are pretty-printed and small
63
+ * strings remain plain text. Oversized values become valid JSON truncation envelopes.
59
64
  */
60
65
  declare function boundedSerialize(data: unknown, budget: number, hint?: string): string;
61
66
  /** Per-tool guidance threaded into the truncation marker when a result is too large. */
@@ -187,4 +192,4 @@ declare function registerMessagingTools(server: McpServer, ctx: ToolContext): vo
187
192
  /** Register the full coach tool surface (roster, teams, programs, exercises, messaging). */
188
193
  declare function registerCoachTools(server: McpServer, ctx: ToolContext): void;
189
194
  //#endregion
190
- export { AthleteContext, BudgetHint, DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SERVER_INSTRUCTIONS, SYNC, ToolContext, ToolHandlerResult, apiCall, apiResponseResult, attempt, boundedSerialize, clipArray, confirmGate, errorResult, idParam, jsonResult, mapSessionExercises, registerAnalyticsTools, registerAthleteTools, registerAthleteTrainingTools, registerCoachTools, registerExerciseTools, registerMainLiftTools, registerMessagingTools, registerProgramTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };
195
+ export { ADDITIVE, AthleteContext, BudgetHint, DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SERVER_INSTRUCTIONS, SYNC, ToolContext, ToolHandlerResult, apiCall, apiResponseResult, attempt, boundedSerialize, clipArray, confirmGate, errorResult, idParam, jsonResult, mapSessionExercises, registerAnalyticsTools, registerAthleteTools, registerAthleteTrainingTools, registerCoachTools, registerExerciseTools, registerMainLiftTools, registerMessagingTools, registerProgramTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };
package/dist/index.mjs CHANGED
@@ -1,4 +1,4 @@
1
- import { athletePrescribeSetArgsSchema, athleteSessionRemoveArgsSchema, blockSpecSchema, coachLogSessionArgsSchema, coachLogSetArgsSchema, coachPrescribeSetArgsSchema, commentDraftSchema, dateString, exerciseCreateSchema, idArgSchema, logSessionArgsSchema, logSetArgsSchema, parseWorkoutDate, sessionTemplateCreateSchema, swapAthleteExerciseArgsSchema, teamPublishPatchObject, teamPublishPatchSchema } from "@trainheroic-unofficial/dto";
1
+ import { athleteExerciseCatalogOutputSchema, athleteInviteOutputSchema, athleteMainLiftPrsOutputSchema, athletePrefsSchema, athletePrescribeSetArgsSchema, athleteProfileOutputSchema, athleteSessionRemoveArgsSchema, athleteSessionRemovedOutputSchema, athleteWorkingMaxListSchema, athleteWorkoutsOutputSchema, blockSpecSchema, coachAthleteTrainingOutputSchema, coachLogSessionArgsSchema, coachLogSetArgsSchema, coachPrescribeSetArgsSchema, commentDraftSchema, dateString, exerciseCreateSchema, exerciseCreatedOutputSchema, exerciseDeletedOutputSchema, exerciseForgottenOutputSchema, exerciseGetOutputSchema, exerciseHistoryOutputSchema, exerciseResolveOutputSchema, exerciseStatsSchema, exerciseSwapOutputSchema, exerciseViewSchema, idArgSchema, logSessionArgsSchema, logSetArgsSchema, logTargetsOutputSchema, messageDeletedOutputSchema, messageDraftOutputSchema, messageSentOutputSchema, opaqueOutputSchema, parseWorkoutDate, personalRecordListSchema, personalWorkoutCreatedOutputSchema, programCreatedOutputSchema, programDeletedOutputSchema, removedSessionOutputSchema, rosterActivityOutputSchema, sessionLogOutputSchema, sessionTemplateCreateSchema, sessionTemplateCreatedOutputSchema, setLogOutputSchema, setPrescriptionOutputSchema, swapAthleteExerciseArgsSchema, teamPublishPatchObject, teamPublishPatchSchema, teamVolumeOutputSchema, toolOutputSchema, userSimpleSchema, workoutBuildOutputSchema, workoutPublishOutputSchema, workoutReadOutputSchema } from "@trainheroic-unofficial/dto";
2
2
  import { acceptedContent, inputRequired, inputResponse } from "@modelcontextprotocol/server";
3
3
  import { z } from "zod";
4
4
  import { ANALYTICS_METRIC_KEYS, PROGRAM_KINDS, SESSION_TEMPLATES_LIST_PATH, addExercisesToWorkout, buildCommentPayload, buildSession, coerceInt, collectAdvisories, copySession, createPersonalWorkout, createProgram, createSessionTemplate, definedProps, deleteComment, deleteProgram, exerciseUnits, fetchAthleteCircuits, fetchAthleteMainLiftPRs, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteProgrammingPrograms, fetchAthleteUser, fetchAthleteWorkouts, fetchCoachAthleteCalendarSummary, fetchCoachAthleteWorkouts, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchRecentExercises, fetchRosterActivity, fetchRosterMainLiftPRs, fetchStreams, fetchTeamAthleteIds, fetchWorkingMaxes, inviteAthletes, isRecord, logAdHocSession, logAthleteSet, logForAthlete, logSessionForAthlete, prescribeAthleteSet, prescribeForAthlete, presentAthleteWorkouts, presentCoachAthleteTraining, presentExerciseHistory, presentLogTargets, publishSession, queryAnalytics, readLive, readSession, removePersonalWorkout, removeSession, resolveBuildProgramId, searchExerciseHistory, selectWorkouts, selectWorkoutsByProgram, sendComment, summarizeAthleteWorkouts, swapAthleteExercise, teamPublishTarget, teamVolume, toSetResults, updateTeam, updateTeamPublishSettings } from "@trainheroic-unofficial/js";
@@ -10,6 +10,12 @@ function toId(value) {
10
10
  }
11
11
  const READ = {
12
12
  readOnlyHint: true,
13
+ destructiveHint: false,
14
+ openWorldHint: true
15
+ };
16
+ const ADDITIVE = {
17
+ readOnlyHint: false,
18
+ destructiveHint: false,
13
19
  openWorldHint: true
14
20
  };
15
21
  const SYNC = {
@@ -37,32 +43,36 @@ async function attempt(fn) {
37
43
  }
38
44
  /** Conservative per-result character cap, below the smallest host cap. */
39
45
  const DEFAULT_RESULT_BUDGET = 6e4;
46
+ /** Smallest cap that can still carry a useful structured truncation envelope. */
47
+ const MIN_RESULT_BUDGET = 256;
40
48
  /** Reserve for the `__truncated` marker so wrapping cannot push back over budget. */
41
49
  const MARKER_RESERVE = 300;
42
50
  const DEFAULT_ARRAY_HINT = "Result was truncated to fit the size budget. Narrow it with a filter/search argument or paginate to see the rest.";
43
51
  const DEFAULT_OBJECT_HINT = "Result was truncated to fit the size budget. Request a more specific id or sub-resource.";
44
52
  /**
45
53
  * Clip an array to its first `keep` items and attach the `__truncated` marker describing what was
46
- * dropped. The marker is model-facing (tools instruct the model to key off `__truncated`), so its
47
- * shape has exactly one definition here: the size-budget path (`boundedSerialize`) and any tool
48
- * that deliberately caps a list (e.g. `athlete_exercises`) emit the same thing.
54
+ * dropped. Every budget fallback that trims a list uses this envelope (`{ items, __truncated }`),
55
+ * including in-place object-array truncation (the sliced array becomes `items` and `field` names
56
+ * the original key). `athlete_exercises` uses the same helper for a client-side catalog cap.
49
57
  */
50
- function clipArray(items, keep, hint) {
58
+ function clipArray(items, keep, hint, field) {
59
+ const marker = {
60
+ returned: keep,
61
+ total: items.length,
62
+ omitted: items.length - keep,
63
+ hint: hint ?? DEFAULT_ARRAY_HINT
64
+ };
65
+ if (field !== void 0) marker.field = field;
51
66
  return {
52
67
  items: items.slice(0, keep),
53
- __truncated: {
54
- returned: keep,
55
- total: items.length,
56
- omitted: items.length - keep,
57
- hint: hint ?? DEFAULT_ARRAY_HINT
58
- }
68
+ __truncated: marker
59
69
  };
60
70
  }
61
71
  /** Active budget. Overridable via TH_MCP_RESULT_BUDGET on Node; the default on workerd. */
62
72
  function resultBudget() {
63
73
  const raw = (globalThis.process?.env)?.TH_MCP_RESULT_BUDGET;
64
74
  const n = raw ? Number(raw) : NaN;
65
- return Number.isFinite(n) && n > 0 ? n : DEFAULT_RESULT_BUDGET;
75
+ return Number.isFinite(n) && n >= MIN_RESULT_BUDGET ? n : DEFAULT_RESULT_BUDGET;
66
76
  }
67
77
  function isPlainObject(value) {
68
78
  return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -79,7 +89,7 @@ function largestPrefixCount(pieces, charBudget) {
79
89
  }
80
90
  return k;
81
91
  }
82
- /** Last resort: cap a string at the budget and label it as truncated, non-JSON output. */
92
+ /** Cap diagnostic text. Tool errors are text-only and are not output-schema validated. */
83
93
  function hardCap(text, budget, hint) {
84
94
  if (text.length <= budget) return text;
85
95
  const note = `\n\n[TRUNCATED: output exceeded ${budget} chars and is NOT valid JSON. ${hint ?? "Narrow the query (filter, paginate, or fetch a specific id)."}]`;
@@ -99,56 +109,86 @@ function largestArrayValuedKey(obj) {
99
109
  }
100
110
  return best;
101
111
  }
102
- /**
103
- * Serialize `data` as JSON within `budget` characters. Small results are pretty-printed.
104
- * Oversized results degrade in order: trim a top-level array (wrapping it as
105
- * `{ items, __truncated }`), then a top-level object's largest array property (annotated
106
- * with `__truncated`), then a last-resort hard character cap. Pure and side-effect free.
107
- */
108
- function boundedSerialize(data, budget, hint) {
109
- if (typeof data === "string") return hardCap(data, budget, hint);
110
- const compact = JSON.stringify(data) ?? "null";
112
+ function jsonValue(data) {
113
+ return JSON.parse(JSON.stringify(data) ?? "null");
114
+ }
115
+ function previewEnvelope(source, budget, hint) {
116
+ const total = source.length;
117
+ const makeValue = (preview, markerHint) => ({
118
+ preview,
119
+ __truncated: {
120
+ total,
121
+ omitted: total - preview.length,
122
+ hint: markerHint
123
+ }
124
+ });
125
+ let markerHint = hint ?? "Narrow the query (filter, paginate, or fetch a specific id).";
126
+ while (JSON.stringify(makeValue("", markerHint)).length > budget && markerHint.length > 0) markerHint = markerHint.slice(0, -1);
127
+ if (JSON.stringify(makeValue("", markerHint)).length > budget) throw new RangeError("Result budget is too small for a structured truncation envelope.");
128
+ let keep = Math.max(0, budget - JSON.stringify(makeValue("", markerHint)).length);
129
+ let value = makeValue(source.slice(0, keep), markerHint);
130
+ while (JSON.stringify(value).length > budget && keep > 0) {
131
+ keep = Math.max(0, keep - (JSON.stringify(value).length - budget));
132
+ value = makeValue(source.slice(0, keep), markerHint);
133
+ }
134
+ return value;
135
+ }
136
+ function boundedResult(data, budget, hint) {
137
+ if (typeof data === "string" && data.length <= budget) return {
138
+ text: data,
139
+ value: data
140
+ };
141
+ const value = jsonValue(data);
142
+ const compact = JSON.stringify(value);
111
143
  if (compact.length <= budget) {
112
- const pretty = JSON.stringify(data, null, 2) ?? "null";
113
- return pretty.length <= budget ? pretty : compact;
144
+ const pretty = JSON.stringify(value, null, 2);
145
+ return {
146
+ text: pretty.length <= budget ? pretty : compact,
147
+ value
148
+ };
114
149
  }
115
- if (Array.isArray(data)) {
116
- const k = largestPrefixCount(data.map((el) => JSON.stringify(el) ?? "null"), budget - MARKER_RESERVE);
117
- const out = JSON.stringify(clipArray(data, k, hint));
118
- if (out.length <= budget) return out;
119
- } else if (isPlainObject(data)) {
120
- const key = largestArrayValuedKey(data);
150
+ if (Array.isArray(value)) {
151
+ const truncated = clipArray(value, largestPrefixCount(value.map((element) => JSON.stringify(element)), budget - MARKER_RESERVE), hint);
152
+ const text = JSON.stringify(truncated);
153
+ if (text.length <= budget) return {
154
+ text,
155
+ value: truncated
156
+ };
157
+ } else if (isPlainObject(value)) {
158
+ const key = largestArrayValuedKey(value);
121
159
  if (key !== null) {
122
- const arr = data[key];
123
- const pieces = arr.map((el) => JSON.stringify(el) ?? "null");
124
- const restLen = (JSON.stringify({
125
- ...data,
126
- [key]: []
127
- }) ?? "{}").length;
128
- const k = largestPrefixCount(pieces, Math.max(0, budget - MARKER_RESERVE - restLen));
129
- const clone = {
130
- ...data,
131
- [key]: arr.slice(0, k),
132
- __truncated: {
133
- field: key,
134
- returned: k,
135
- total: arr.length,
136
- omitted: arr.length - k,
137
- hint: hint ?? DEFAULT_OBJECT_HINT
138
- }
160
+ const array = value[key];
161
+ const truncated = clipArray(array, largestPrefixCount(array.map((element) => JSON.stringify(element)), budget - MARKER_RESERVE), hint ?? DEFAULT_OBJECT_HINT, key);
162
+ const text = JSON.stringify(truncated);
163
+ if (text.length <= budget) return {
164
+ text,
165
+ value: truncated
139
166
  };
140
- const out = JSON.stringify(clone);
141
- if (out.length <= budget) return out;
142
167
  }
143
168
  }
144
- return hardCap(compact, budget, hint);
169
+ const truncated = previewEnvelope(typeof data === "string" ? data : compact, budget, hint);
170
+ return {
171
+ text: JSON.stringify(truncated),
172
+ value: truncated
173
+ };
174
+ }
175
+ /**
176
+ * Serialize `data` within `budget` characters. Small JSON results are pretty-printed and small
177
+ * strings remain plain text. Oversized values become valid JSON truncation envelopes.
178
+ */
179
+ function boundedSerialize(data, budget, hint) {
180
+ return boundedResult(data, budget, hint).text;
145
181
  }
146
182
  /** A successful tool result carrying JSON (or text) for the model, size-bounded. */
147
183
  function jsonResult(data, opts) {
148
- return { content: [{
149
- type: "text",
150
- text: boundedSerialize(data, resultBudget(), opts?.hint)
151
- }] };
184
+ const { text, value } = boundedResult(data, resultBudget(), opts?.hint);
185
+ return {
186
+ content: [{
187
+ type: "text",
188
+ text
189
+ }],
190
+ structuredContent: value
191
+ };
152
192
  }
153
193
  /** A tool-level error: returned in-band (isError) so the model can self-correct. */
154
194
  function errorResult(message) {
@@ -263,12 +303,6 @@ function enc(value) {
263
303
  }
264
304
  /** No-argument GET endpoints, registered from a table to keep the wiring compact. */
265
305
  const SIMPLE_GETS = [
266
- {
267
- name: "whoami",
268
- title: "Who am I",
269
- description: "The authenticated TrainHeroic coach profile (id, org_id, name, roles, trial days).",
270
- path: "/user/simple"
271
- },
272
306
  {
273
307
  name: "head_coach",
274
308
  title: "Head coach / org",
@@ -320,10 +354,18 @@ const SIMPLE_GETS = [
320
354
  ];
321
355
  /** Roster-level reads: the fixed GETs plus the filterable athlete and team lists. */
322
356
  function registerRosterReads(server, ctx) {
357
+ server.registerTool("whoami", {
358
+ title: "Who am I",
359
+ description: "The authenticated TrainHeroic coach profile (id, org_id, name, roles, trial days).",
360
+ inputSchema: {},
361
+ outputSchema: toolOutputSchema(userSimpleSchema),
362
+ annotations: READ
363
+ }, () => apiCall(ctx, "GET", "/user/simple"));
323
364
  for (const t of SIMPLE_GETS) server.registerTool(t.name, {
324
365
  title: t.title,
325
366
  description: t.description,
326
367
  inputSchema: {},
368
+ outputSchema: opaqueOutputSchema,
327
369
  annotations: READ
328
370
  }, () => apiCall(ctx, "GET", t.path));
329
371
  server.registerTool("list_athletes", {
@@ -333,6 +375,7 @@ function registerRosterReads(server, ctx) {
333
375
  q: z.string().optional(),
334
376
  limit: z.number().int().positive().max(500).optional()
335
377
  },
378
+ outputSchema: toolOutputSchema(z.array(z.json())),
336
379
  annotations: READ
337
380
  }, ({ q, limit }) => attempt(async () => {
338
381
  const res = await ctx.client.request("GET", "/v5/athletes");
@@ -349,13 +392,7 @@ function registerRosterReads(server, ctx) {
349
392
  return needles.every((n) => hay.includes(n));
350
393
  });
351
394
  }
352
- const total = rows.length;
353
- if (limit !== void 0 && rows.length > limit) return jsonResult({
354
- items: rows.slice(0, limit),
355
- returned: limit,
356
- total,
357
- note: "Limited client-side. Raise limit or narrow with q for the rest."
358
- });
395
+ if (limit !== void 0 && rows.length > limit) return jsonResult(clipArray(rows, limit, "Limited client-side. Raise limit or narrow with q for the rest."));
359
396
  return jsonResult(rows, { hint: "Filter with q (name/email substring) or cap with limit to shrink this list." });
360
397
  }));
361
398
  server.registerTool("list_teams", {
@@ -366,6 +403,7 @@ function registerRosterReads(server, ctx) {
366
403
  pageSize: z.number().int().positive().optional(),
367
404
  q: z.string().optional()
368
405
  },
406
+ outputSchema: opaqueOutputSchema,
369
407
  annotations: READ
370
408
  }, ({ page, pageSize, q }) => {
371
409
  const qs = new URLSearchParams();
@@ -382,12 +420,14 @@ function registerEntityReads(server, ctx) {
382
420
  title: "Get team",
383
421
  description: "Full team object by team id.",
384
422
  inputSchema: { teamId: idParam },
423
+ outputSchema: opaqueOutputSchema,
385
424
  annotations: READ
386
425
  }, ({ teamId }) => apiCall(ctx, "GET", `/v5/teams/${enc(teamId)}`));
387
426
  server.registerTool("list_team_codes", {
388
427
  title: "List team access codes",
389
428
  description: "Join/access codes for a team.",
390
429
  inputSchema: { teamId: idParam },
430
+ outputSchema: opaqueOutputSchema,
391
431
  annotations: READ
392
432
  }, ({ teamId }) => apiCall(ctx, "GET", `/v5/teams/${enc(teamId)}/teamCodes`));
393
433
  server.registerTool("athlete_lift_history", {
@@ -400,6 +440,7 @@ function registerEntityReads(server, ctx) {
400
440
  since: dateString.optional(),
401
441
  until: dateString.optional()
402
442
  },
443
+ outputSchema: toolOutputSchema(exerciseHistoryOutputSchema),
403
444
  annotations: READ
404
445
  }, ({ athleteId, exerciseId, raw, since, until }) => attempt(async () => {
405
446
  const detail = await fetchExerciseHistoryDetail(ctx.client, toId(exerciseId), toId(athleteId));
@@ -413,6 +454,7 @@ function registerEntityReads(server, ctx) {
413
454
  athleteIds: z.array(idParam).min(1),
414
455
  useMetric: z.boolean().optional()
415
456
  },
457
+ outputSchema: toolOutputSchema(rosterActivityOutputSchema),
416
458
  annotations: READ
417
459
  }, ({ athleteIds, useMetric }) => attempt(async () => jsonResult(await fetchRosterActivity(ctx.client, athleteIds.map(toId), useMetric ?? false), { hint: "Sorted most-recently-active first; lastLoggedDate null = never logged. The top row is the most recently active athlete." })));
418
460
  server.registerTool("athlete_training", {
@@ -423,6 +465,7 @@ function registerEntityReads(server, ctx) {
423
465
  year: z.number().int(),
424
466
  month: z.number().int().min(1).max(12)
425
467
  },
468
+ outputSchema: toolOutputSchema(coachAthleteTrainingOutputSchema),
426
469
  annotations: READ
427
470
  }, ({ athleteId, year, month }) => attempt(async () => {
428
471
  const raw = await fetchCoachAthleteCalendarSummary(ctx.client, toId(athleteId), year, month);
@@ -432,6 +475,7 @@ function registerEntityReads(server, ctx) {
432
475
  title: "Get program detail",
433
476
  description: "Program detail live from the API, by program id. Works for team calendars and athlete coach calendars (type 5 from /v5/calendars/athletes/{id}). For standalone rows from list_programs, accepts either id (the container id) or group_program (the underlying program id); container ids are resolved automatically. If neither detail endpoint is available, returns calendar metadata and next-step guidance instead.",
434
477
  inputSchema: { programId: idParam },
478
+ outputSchema: opaqueOutputSchema,
435
479
  annotations: READ
436
480
  }, ({ programId }) => getProgram(ctx, toId(programId)));
437
481
  }
@@ -466,6 +510,7 @@ function registerTeamVolume(server, ctx) {
466
510
  dateStart: dateString,
467
511
  dateEnd: dateString
468
512
  },
513
+ outputSchema: toolOutputSchema(teamVolumeOutputSchema),
469
514
  annotations: READ
470
515
  }, ({ teamId, athleteIds, dateStart, dateEnd }) => attempt(async () => {
471
516
  const ids = athleteIds !== void 0 && athleteIds.length > 0 ? athleteIds.map(toId) : teamId !== void 0 ? await fetchTeamAthleteIds(ctx.client, toId(teamId)) : [];
@@ -488,6 +533,7 @@ function registerCoachAthleteTeamCalendar(server, ctx) {
488
533
  title: "Coach-athlete team calendar",
489
534
  description: "Companion calendar for a roster athlete (GET /v5/calendars/athletes/{id}/coachAthleteTeam). Distinct from workout_build's type-5 individual calendar. Returns title, logo, id, athlete_id, owner_user_id.",
490
535
  inputSchema: { athleteId: idParam },
536
+ outputSchema: opaqueOutputSchema,
491
537
  annotations: READ
492
538
  }, ({ athleteId }) => apiCall(ctx, "GET", `/v5/calendars/athletes/${toId(athleteId)}/coachAthleteTeam`));
493
539
  }
@@ -505,6 +551,7 @@ function registerMainLiftTools(server, ctx) {
505
551
  athleteId: idParam,
506
552
  months: monthsParam
507
553
  },
554
+ outputSchema: toolOutputSchema(athleteMainLiftPrsOutputSchema),
508
555
  annotations: READ
509
556
  }, ({ athleteId, months }) => attempt(async () => jsonResult(await fetchAthleteMainLiftPRs(ctx.client, toId(athleteId), months !== void 0 ? { months } : {}))));
510
557
  server.registerTool("roster_main_lift_prs", {
@@ -514,6 +561,7 @@ function registerMainLiftTools(server, ctx) {
514
561
  months: monthsParam,
515
562
  athleteIds: z.array(idParam).optional()
516
563
  },
564
+ outputSchema: toolOutputSchema(z.array(athleteMainLiftPrsOutputSchema)),
517
565
  annotations: READ
518
566
  }, ({ months, athleteIds }) => attempt(async () => {
519
567
  return jsonResult(await fetchRosterMainLiftPRs(ctx.client, {
@@ -530,12 +578,14 @@ function registerProfileTools(server, ctx, whoami, userId) {
530
578
  title: "Who am I (athlete)",
531
579
  description: "The logged-in account's identity (id, name, roles) from /user/simple.",
532
580
  inputSchema: {},
581
+ outputSchema: toolOutputSchema(userSimpleSchema),
533
582
  annotations: READ
534
583
  }, () => attempt(async () => jsonResult(await whoami())));
535
584
  server.registerTool("athlete_profile", {
536
585
  title: "Athlete profile + lifetime totals",
537
586
  description: "Lifetime training totals in one call — all-time session count (summary.sessions_count), total reps and volume, first/last logged date — plus the profile (name, units, dob). Use this for any 'how many sessions all-time / total volume ever' question rather than summing athlete_workouts windows. Set useMetric for kg/metric totals.",
538
587
  inputSchema: { useMetric: z.boolean().optional() },
588
+ outputSchema: toolOutputSchema(athleteProfileOutputSchema),
539
589
  annotations: READ
540
590
  }, ({ useMetric }) => attempt(async () => {
541
591
  const id = await userId();
@@ -549,12 +599,14 @@ function registerProfileTools(server, ctx, whoami, userId) {
549
599
  title: "Athlete preferences",
550
600
  description: "Notification and display preference flags for the athlete account.",
551
601
  inputSchema: {},
602
+ outputSchema: toolOutputSchema(athletePrefsSchema),
552
603
  annotations: READ
553
604
  }, () => attempt(async () => jsonResult(await fetchAthletePrefs(ctx.client))));
554
605
  server.registerTool("athlete_working_maxes", {
555
606
  title: "Working maxes",
556
607
  description: "The athlete's working max per exercise (drives % prescriptions). An entry can carry a null value: the exercise has a working-max slot but no number has been set yet, which means there is effectively no working max for it.",
557
608
  inputSchema: {},
609
+ outputSchema: toolOutputSchema(athleteWorkingMaxListSchema),
558
610
  annotations: READ
559
611
  }, () => attempt(async () => jsonResult(await fetchWorkingMaxes(ctx.client))));
560
612
  server.registerTool("athlete_leaderboard", {
@@ -566,6 +618,7 @@ function registerProfileTools(server, ctx, whoami, userId) {
566
618
  pageSize: z.number().int().positive().max(200).optional(),
567
619
  gender: z.number().int().optional()
568
620
  },
621
+ outputSchema: opaqueOutputSchema,
569
622
  annotations: READ
570
623
  }, ({ workoutId, page, pageSize, gender }) => attempt(async () => {
571
624
  const opts = {};
@@ -622,6 +675,7 @@ function registerExerciseTools$1(server, ctx, userId) {
622
675
  limit: z.number().int().positive().max(200).optional(),
623
676
  summary: z.boolean().optional()
624
677
  },
678
+ outputSchema: toolOutputSchema(athleteWorkoutsOutputSchema),
625
679
  annotations: READ
626
680
  }, (args) => runAthleteWorkouts(ctx, args));
627
681
  server.registerTool("athlete_exercises", {
@@ -631,6 +685,7 @@ function registerExerciseTools$1(server, ctx, userId) {
631
685
  q: z.string().optional(),
632
686
  limit: z.number().int().positive().optional()
633
687
  },
688
+ outputSchema: toolOutputSchema(athleteExerciseCatalogOutputSchema),
634
689
  annotations: READ
635
690
  }, (args) => runAthleteExercises(ctx, args));
636
691
  server.registerTool("athlete_exercise_history", {
@@ -642,6 +697,7 @@ function registerExerciseTools$1(server, ctx, userId) {
642
697
  since: dateString.optional(),
643
698
  until: dateString.optional()
644
699
  },
700
+ outputSchema: toolOutputSchema(exerciseHistoryOutputSchema),
645
701
  annotations: READ
646
702
  }, ({ exerciseId, raw, since, until }) => attempt(async () => {
647
703
  const detail = await fetchExerciseHistoryDetail(ctx.client, toId(exerciseId), await userId());
@@ -652,6 +708,7 @@ function registerExerciseTools$1(server, ctx, userId) {
652
708
  title: "Exercise personal records",
653
709
  description: "The all-time PR board for an exercise (reps/weight per rep-max, strength-standard filters). Get the exercise id from athlete_exercises. A lift is often logged under several name variants, each with its own board, so if a PR looks missing check the other variants. For a point-in-time snapshot use athlete_exercise_stats; for the dated session trend use athlete_exercise_history.",
654
710
  inputSchema: { exerciseId: idParam },
711
+ outputSchema: toolOutputSchema(personalRecordListSchema),
655
712
  annotations: READ
656
713
  }, ({ exerciseId }) => attempt(async () => jsonResult(await fetchPersonalRecords(ctx.client, toId(exerciseId)))));
657
714
  server.registerTool("athlete_exercise_stats", {
@@ -661,6 +718,7 @@ function registerExerciseTools$1(server, ctx, userId) {
661
718
  exerciseId: idParam,
662
719
  date: dateString
663
720
  },
721
+ outputSchema: toolOutputSchema(exerciseStatsSchema),
664
722
  annotations: READ
665
723
  }, ({ exerciseId, date }) => attempt(async () => jsonResult(await fetchExerciseStats(ctx.client, toId(exerciseId), await userId(), date))));
666
724
  }
@@ -677,6 +735,7 @@ function registerLogTargetsTool(server, ctx) {
677
735
  teamId: idParam.optional(),
678
736
  raw: z.boolean().optional()
679
737
  },
738
+ outputSchema: toolOutputSchema(logTargetsOutputSchema),
680
739
  annotations: READ
681
740
  }, ({ startDate, endDate, program, programId, teamId, raw }) => attempt(async () => {
682
741
  const all = await fetchAthleteWorkouts(ctx.client, startDate, endDate);
@@ -696,11 +755,8 @@ function registerSessionTools(server, ctx) {
696
755
  title: "Create personal workout session",
697
756
  description: "Create a new personal workout session for a given YYYY-MM-DD date on the athlete's personal calendar. Returns programWorkoutId, workoutId (pass to athlete_session_add_exercises), savedWorkoutId, groupId, and date.",
698
757
  inputSchema: { date: dateString },
699
- annotations: {
700
- readOnlyHint: false,
701
- destructiveHint: false,
702
- openWorldHint: true
703
- }
758
+ outputSchema: toolOutputSchema(personalWorkoutCreatedOutputSchema),
759
+ annotations: ADDITIVE
704
760
  }, ({ date }) => attempt(async () => jsonResult(await createPersonalWorkout(ctx.client, date))));
705
761
  server.registerTool("athlete_session_add_exercises", {
706
762
  title: "Add exercises to a personal workout session",
@@ -712,11 +768,8 @@ function registerSessionTools(server, ctx) {
712
768
  order: z.number().int().positive()
713
769
  })).min(1)
714
770
  },
715
- annotations: {
716
- readOnlyHint: false,
717
- destructiveHint: false,
718
- openWorldHint: true
719
- }
771
+ outputSchema: opaqueOutputSchema,
772
+ annotations: ADDITIVE
720
773
  }, ({ workoutId, exercises }) => attempt(async () => {
721
774
  const mapped = exercises.map((e) => ({
722
775
  exerciseId: toId(e.exerciseId),
@@ -731,6 +784,7 @@ function registerSessionTools(server, ctx) {
731
784
  ...athleteSessionRemoveArgsSchema.shape,
732
785
  confirm: z.boolean().optional()
733
786
  },
787
+ outputSchema: toolOutputSchema(athleteSessionRemovedOutputSchema),
734
788
  annotations: DESTRUCTIVE
735
789
  }, ({ programWorkoutId, date, confirm }, extra) => attempt(async () => {
736
790
  const id = toId(programWorkoutId);
@@ -773,6 +827,7 @@ function registerLogTool(server, ctx) {
773
827
  ...logSessionArgsSchema.shape,
774
828
  confirm: z.boolean().optional()
775
829
  },
830
+ outputSchema: toolOutputSchema(sessionLogOutputSchema),
776
831
  annotations: DESTRUCTIVE
777
832
  }, ({ date, exercises, confirm }, extra) => attempt(async () => {
778
833
  const blocked = confirmGate(extra, `Log a session of ${exercises.length} exercise(s) on ${date}? This writes to your coach-visible training log.`, confirm);
@@ -791,6 +846,7 @@ function registerLogTool(server, ctx) {
791
846
  ...logSetArgsSchema.shape,
792
847
  confirm: z.boolean().optional()
793
848
  },
849
+ outputSchema: toolOutputSchema(setLogOutputSchema),
794
850
  annotations: DESTRUCTIVE
795
851
  }, ({ date, savedWorkoutSetId, results, confirm }, extra) => attempt(async () => {
796
852
  const blocked = confirmGate(extra, `Log results to saved workout set ${toId(savedWorkoutSetId)} on ${date}? This writes to your coach-visible training log.`, confirm);
@@ -808,6 +864,7 @@ function registerLogTool(server, ctx) {
808
864
  ...athletePrescribeSetArgsSchema.shape,
809
865
  confirm: z.boolean().optional()
810
866
  },
867
+ outputSchema: toolOutputSchema(setPrescriptionOutputSchema),
811
868
  annotations: DESTRUCTIVE
812
869
  }, ({ date, savedWorkoutSetId, results, confirm }, extra) => attempt(async () => {
813
870
  const id = toId(savedWorkoutSetId);
@@ -834,6 +891,7 @@ function registerSwapTool(server, ctx) {
834
891
  ...swapAthleteExerciseArgsSchema.shape,
835
892
  confirm: z.boolean().optional()
836
893
  },
894
+ outputSchema: toolOutputSchema(exerciseSwapOutputSchema),
837
895
  annotations: DESTRUCTIVE
838
896
  }, ({ savedWorkoutSetExerciseId, exerciseId, confirm }, extra) => attempt(async () => {
839
897
  const sweId = toId(savedWorkoutSetExerciseId);
@@ -851,18 +909,21 @@ function registerCatalogReads(server, ctx) {
851
909
  title: "Circuit history",
852
910
  description: "Named circuit history for the logged-in athlete (GET /v5/users/circuits/{recent|history}). kind defaults to recent. Empty when the athlete has no saved circuits. Distinct from circuit *blocks* in workout_build (type 1).",
853
911
  inputSchema: { kind: z.enum(["recent", "history"]).optional() },
912
+ outputSchema: opaqueOutputSchema,
854
913
  annotations: READ
855
914
  }, ({ kind }) => attempt(async () => jsonResult(await fetchAthleteCircuits(ctx.client, kind ?? "recent"))));
856
915
  server.registerTool("athlete_programming_programs", {
857
916
  title: "Subscribed programs",
858
917
  description: "Programs the athlete is subscribed to (GET /1.0/athlete/programming/programs). Not the coach list_programs surface. Empty when the athlete has no subscriptions.",
859
918
  inputSchema: {},
919
+ outputSchema: opaqueOutputSchema,
860
920
  annotations: READ
861
921
  }, () => attempt(async () => jsonResult(await fetchAthleteProgrammingPrograms(ctx.client))));
862
922
  server.registerTool("athlete_recent_exercises", {
863
923
  title: "Recent exercises",
864
924
  description: "Recently used exercises (GET /v5/users/exercises/recent). Distinct from athlete_exercises (full logged catalog) and athlete_exercise_history (one lift).",
865
925
  inputSchema: {},
926
+ outputSchema: opaqueOutputSchema,
866
927
  annotations: READ
867
928
  }, () => attempt(async () => jsonResult(await fetchRecentExercises(ctx.client))));
868
929
  }
@@ -917,6 +978,7 @@ function registerAthleteTools(server, ctx) {
917
978
  message: z.string().optional(),
918
979
  confirm: z.boolean().optional()
919
980
  },
981
+ outputSchema: toolOutputSchema(athleteInviteOutputSchema),
920
982
  annotations: DESTRUCTIVE
921
983
  }, ({ teamId, emails, message, confirm }, extra) => attempt(async () => {
922
984
  const list = asEmailList(emails);
@@ -941,6 +1003,7 @@ function registerAthleteTools(server, ctx) {
941
1003
  athleteIds: z.array(idParam).min(1),
942
1004
  confirm: z.boolean().optional()
943
1005
  },
1006
+ outputSchema: opaqueOutputSchema,
944
1007
  annotations: DESTRUCTIVE
945
1008
  }, ({ athleteIds, confirm }, extra) => attempt(async () => {
946
1009
  const ids = athleteIds.map(toId);
@@ -952,6 +1015,7 @@ function registerAthleteTools(server, ctx) {
952
1015
  title: "Restore athletes",
953
1016
  description: "Restore previously archived athletes to the active roster (PUT /v5/athletes/restore).",
954
1017
  inputSchema: { athleteIds: z.array(idParam).min(1) },
1018
+ outputSchema: opaqueOutputSchema,
955
1019
  annotations: {
956
1020
  readOnlyHint: false,
957
1021
  idempotentHint: true,
@@ -982,6 +1046,7 @@ function registerAthleteSavedWorkouts(server, ctx) {
982
1046
  teamId: idParam.optional(),
983
1047
  raw: z.boolean().optional()
984
1048
  },
1049
+ outputSchema: toolOutputSchema(logTargetsOutputSchema),
985
1050
  annotations: READ
986
1051
  }, ({ athleteId, startDate, endDate, program, programId, teamId, raw }) => attempt(async () => {
987
1052
  const all = await fetchCoachAthleteWorkouts(ctx.client, toId(athleteId), startDate, endDate);
@@ -1004,6 +1069,7 @@ function registerAthleteLogTools(server, ctx) {
1004
1069
  ...coachLogSetArgsSchema.shape,
1005
1070
  confirm: z.boolean().optional()
1006
1071
  },
1072
+ outputSchema: toolOutputSchema(setLogOutputSchema),
1007
1073
  annotations: DESTRUCTIVE
1008
1074
  }, ({ athleteId, date, savedWorkoutSetId, results, confirm }, extra) => attempt(async () => {
1009
1075
  const aId = toId(athleteId);
@@ -1023,6 +1089,7 @@ function registerAthleteLogTools(server, ctx) {
1023
1089
  ...coachLogSessionArgsSchema.shape,
1024
1090
  confirm: z.boolean().optional()
1025
1091
  },
1092
+ outputSchema: toolOutputSchema(sessionLogOutputSchema),
1026
1093
  annotations: DESTRUCTIVE
1027
1094
  }, ({ athleteId, date, exercises, confirm }, extra) => attempt(async () => {
1028
1095
  const aId = toId(athleteId);
@@ -1047,6 +1114,7 @@ function registerAthleteSwapTool(server, ctx) {
1047
1114
  ...swapAthleteExerciseArgsSchema.shape,
1048
1115
  confirm: z.boolean().optional()
1049
1116
  },
1117
+ outputSchema: toolOutputSchema(exerciseSwapOutputSchema),
1050
1118
  annotations: DESTRUCTIVE
1051
1119
  }, ({ savedWorkoutSetExerciseId, exerciseId, confirm }, extra) => attempt(async () => {
1052
1120
  const sweId = toId(savedWorkoutSetExerciseId);
@@ -1072,6 +1140,7 @@ function registerAthletePrescribeTool(server, ctx) {
1072
1140
  ...coachPrescribeSetArgsSchema.shape,
1073
1141
  confirm: z.boolean().optional()
1074
1142
  },
1143
+ outputSchema: toolOutputSchema(setPrescriptionOutputSchema),
1075
1144
  annotations: DESTRUCTIVE
1076
1145
  }, ({ athleteId, date, savedWorkoutSetId, results, confirm }, extra) => attempt(async () => {
1077
1146
  const aId = toId(athleteId);
@@ -1087,11 +1156,6 @@ function registerAthletePrescribeTool(server, ctx) {
1087
1156
  }
1088
1157
  //#endregion
1089
1158
  //#region src/tools/teams.ts
1090
- const ADDITIVE$1 = {
1091
- readOnlyHint: false,
1092
- destructiveHint: false,
1093
- openWorldHint: true
1094
- };
1095
1159
  /**
1096
1160
  * Team write tools. The team reads (list_teams, get_team, list_team_codes) live in
1097
1161
  * reads.ts; this module covers create/rename/delete plus the join-code lifecycle.
@@ -1101,19 +1165,25 @@ function registerTeamTools(server, ctx) {
1101
1165
  title: "Create a team",
1102
1166
  description: "Create a team (POST /1.0/coach/team/createWithTitleAndCode). Also creates the team's calendar/program. Returns the new team including its calendar id. Use the team id with athlete_invite. To point a new team at an existing calendar instead of its auto-created one, follow up with team_update groupProgram.",
1103
1167
  inputSchema: { title: z.string().min(1) },
1104
- annotations: ADDITIVE$1
1168
+ outputSchema: opaqueOutputSchema,
1169
+ annotations: ADDITIVE
1105
1170
  }, ({ title }) => apiCall(ctx, "POST", "/1.0/coach/team/createWithTitleAndCode", { body: { title } }));
1106
1171
  server.registerTool("team_update", {
1107
1172
  title: "Update a team",
1108
- description: "Update a team's title and/or reassign its calendar (PUT /v5/teams/{teamId}). Pass groupProgram (a program/calendar id — typically another team's group_program from list_teams, or get_team) to point this team at an existing parent program. At least one of title or groupProgram is required; when only groupProgram is set the current title is preserved.",
1173
+ description: "Update a team's title and/or reassign its calendar (PUT /v5/teams/{teamId}). Pass groupProgram (a program/calendar id — typically another team's group_program from list_teams, or get_team) to point this team at an existing parent program. At least one of title or groupProgram is required; when only groupProgram is set the current title is preserved. Requires confirmation (elicitation, or confirm:true).",
1109
1174
  inputSchema: {
1110
1175
  teamId: idParam,
1111
1176
  title: z.string().min(1).optional(),
1112
- groupProgram: idParam.optional()
1177
+ groupProgram: idParam.optional(),
1178
+ confirm: z.boolean().optional()
1113
1179
  },
1114
- annotations: ADDITIVE$1
1115
- }, ({ teamId, title, groupProgram }) => attempt(async () => {
1116
- const args = { teamId: toId(teamId) };
1180
+ outputSchema: opaqueOutputSchema,
1181
+ annotations: DESTRUCTIVE
1182
+ }, ({ teamId, title, groupProgram, confirm }, extra) => attempt(async () => {
1183
+ const id = toId(teamId);
1184
+ const blocked = confirmGate(extra, `Update team ${id}? This overwrites its live title and/or calendar assignment.`, confirm);
1185
+ if (blocked) return blocked;
1186
+ const args = { teamId: id };
1117
1187
  if (title !== void 0) args.title = title;
1118
1188
  if (groupProgram !== void 0) args.groupProgram = toId(groupProgram);
1119
1189
  return jsonResult(await updateTeam(ctx.client, args));
@@ -1125,6 +1195,7 @@ function registerTeamTools(server, ctx) {
1125
1195
  teamId: idParam,
1126
1196
  confirm: z.boolean().optional()
1127
1197
  },
1198
+ outputSchema: opaqueOutputSchema,
1128
1199
  annotations: DESTRUCTIVE
1129
1200
  }, ({ teamId, confirm }, extra) => attempt(async () => {
1130
1201
  const id = toId(teamId);
@@ -1139,7 +1210,8 @@ function registerTeamTools(server, ctx) {
1139
1210
  teamId: idParam,
1140
1211
  type: z.number().int().optional()
1141
1212
  },
1142
- annotations: ADDITIVE$1
1213
+ outputSchema: opaqueOutputSchema,
1214
+ annotations: ADDITIVE
1143
1215
  }, ({ teamId, type }) => apiCall(ctx, "POST", `/v5/teams/${toId(teamId)}/teamCodes`, { body: { type: type ?? 2 } }));
1144
1216
  server.registerTool("team_code_delete", {
1145
1217
  title: "Delete a team join code",
@@ -1148,6 +1220,7 @@ function registerTeamTools(server, ctx) {
1148
1220
  codeId: idParam,
1149
1221
  confirm: z.boolean().optional()
1150
1222
  },
1223
+ outputSchema: opaqueOutputSchema,
1151
1224
  annotations: DESTRUCTIVE
1152
1225
  }, ({ codeId, confirm }, extra) => attempt(async () => {
1153
1226
  const id = toId(codeId);
@@ -1167,6 +1240,7 @@ function registerTeamPublishSettings(server, ctx) {
1167
1240
  ...teamPublishPatchObject.shape,
1168
1241
  confirm: z.boolean().optional()
1169
1242
  },
1243
+ outputSchema: opaqueOutputSchema,
1170
1244
  annotations: DESTRUCTIVE
1171
1245
  }, ({ teamId, programId, pub_enabled, pub_days, pub_time, pub_timezone, confirm }, extra) => attempt(async () => {
1172
1246
  const blocked = confirmGate(extra, "Change auto-publish settings? This controls when athletes see programmed sessions.", confirm);
@@ -1189,11 +1263,6 @@ function registerTeamPublishSettings(server, ctx) {
1189
1263
  }
1190
1264
  //#endregion
1191
1265
  //#region src/tools/programs.ts
1192
- const ADDITIVE = {
1193
- readOnlyHint: false,
1194
- destructiveHint: false,
1195
- openWorldHint: true
1196
- };
1197
1266
  /** Standalone program writes. Program reads live in reads.ts. */
1198
1267
  function registerProgramTools(server, ctx) {
1199
1268
  server.registerTool("program_create", {
@@ -1203,6 +1272,7 @@ function registerProgramTools(server, ctx) {
1203
1272
  kind: z.enum(PROGRAM_KINDS),
1204
1273
  name: z.string().trim().min(1)
1205
1274
  },
1275
+ outputSchema: toolOutputSchema(programCreatedOutputSchema),
1206
1276
  annotations: ADDITIVE
1207
1277
  }, ({ kind, name }) => attempt(async () => jsonResult(await createProgram(ctx.client, {
1208
1278
  kind,
@@ -1215,6 +1285,7 @@ function registerProgramTools(server, ctx) {
1215
1285
  programId: idParam,
1216
1286
  confirm: z.boolean().optional()
1217
1287
  },
1288
+ outputSchema: toolOutputSchema(programDeletedOutputSchema),
1218
1289
  annotations: DESTRUCTIVE
1219
1290
  }, ({ programId, confirm }, extra) => attempt(async () => {
1220
1291
  const id = toId(programId);
@@ -1241,6 +1312,7 @@ function registerAnalyticsTools(server, ctx) {
1241
1312
  dateEnd: z.string().optional(),
1242
1313
  useMetric: z.boolean().optional()
1243
1314
  },
1315
+ outputSchema: opaqueOutputSchema,
1244
1316
  annotations: READ
1245
1317
  }, ({ metric, teamId, userIds, exerciseId, date, dateStart, dateEnd, useMetric }) => attempt(async () => jsonResult(await queryAnalytics(ctx.client, definedProps({
1246
1318
  metric,
@@ -1258,17 +1330,20 @@ function registerAnalyticsTools(server, ctx) {
1258
1330
  function registerExerciseUpdate(server, index) {
1259
1331
  server.registerTool("exercise_update", {
1260
1332
  title: "Update custom exercise",
1261
- description: "Update a custom exercise (POST /2.0/coach/exercise/update/{id}) and write it through to the mirror. Same body as exercise_create. Only works for exercises with can_edit:1.",
1333
+ description: "Update a custom exercise (POST /2.0/coach/exercise/update/{id}) and write it through to the mirror. Same body as exercise_create. Only works for exercises with can_edit:1. Requires confirmation (elicitation, or confirm:true).",
1262
1334
  inputSchema: {
1263
1335
  id: idParam,
1264
- exercise: exerciseCreateSchema
1336
+ exercise: exerciseCreateSchema,
1337
+ confirm: z.boolean().optional()
1265
1338
  },
1266
- annotations: {
1267
- readOnlyHint: false,
1268
- destructiveHint: false,
1269
- openWorldHint: true
1270
- }
1271
- }, ({ id, exercise }) => attempt(async () => jsonResult(await index.update(toId(id), exercise))));
1339
+ outputSchema: toolOutputSchema(exerciseCreatedOutputSchema),
1340
+ annotations: DESTRUCTIVE
1341
+ }, ({ id, exercise, confirm }, extra) => attempt(async () => {
1342
+ const exerciseId = toId(id);
1343
+ const blocked = confirmGate(extra, `Update custom exercise ${exerciseId}? This overwrites its live TrainHeroic definition.`, confirm);
1344
+ if (blocked) return blocked;
1345
+ return jsonResult(await index.update(exerciseId, exercise));
1346
+ }));
1272
1347
  }
1273
1348
  function registerExerciseDelete(server, index) {
1274
1349
  server.registerTool("exercise_delete", {
@@ -1278,6 +1353,7 @@ function registerExerciseDelete(server, index) {
1278
1353
  id: idParam,
1279
1354
  confirm: z.boolean().optional()
1280
1355
  },
1356
+ outputSchema: toolOutputSchema(exerciseDeletedOutputSchema),
1281
1357
  annotations: DESTRUCTIVE
1282
1358
  }, ({ id, confirm }, extra) => attempt(async () => {
1283
1359
  const exerciseId = toId(id);
@@ -1287,17 +1363,12 @@ function registerExerciseDelete(server, index) {
1287
1363
  return jsonResult({ deleted: exerciseId });
1288
1364
  }));
1289
1365
  }
1290
- /**
1291
- * Exercise library tools over the ExerciseIndex — a D1 mirror on the hosted server, an
1292
- * on-disk/in-memory cache locally. The descriptions stay at the interface level so they
1293
- * read correctly on both backends.
1294
- */
1295
- function registerExerciseTools(server, ctx) {
1296
- const index = ctx.index;
1366
+ function registerExerciseReads(server, index) {
1297
1367
  server.registerTool("exercise_resolve", {
1298
1368
  title: "Resolve exercise name",
1299
1369
  description: "Map a name to an exercise id via the local mirror. Prefer this over exercise_search when you want a single authoritative id for a known name. Returns the match plus ranked candidates; when ambiguous, match is null and you should pick from candidates. Each result's `units` array lists the fixed measurement units by entry slot; they are fixed per exercise — check them before prescribing. `can_edit` is 1 only for the coach's own custom exercises and 0 for built-in library exercises.",
1300
1370
  inputSchema: { name: z.string().min(1) },
1371
+ outputSchema: toolOutputSchema(exerciseResolveOutputSchema),
1301
1372
  annotations: READ
1302
1373
  }, ({ name }) => attempt(async () => jsonResult(await index.resolve(name))));
1303
1374
  server.registerTool("exercise_search", {
@@ -1307,12 +1378,14 @@ function registerExerciseTools(server, ctx) {
1307
1378
  query: z.string().min(1),
1308
1379
  limit: z.number().int().positive().max(100).optional()
1309
1380
  },
1381
+ outputSchema: toolOutputSchema(z.array(exerciseViewSchema)),
1310
1382
  annotations: READ
1311
1383
  }, ({ query, limit }) => attempt(async () => jsonResult(await index.search(query, limit ?? 20))));
1312
1384
  server.registerTool("exercise_get", {
1313
1385
  title: "Get exercise",
1314
1386
  description: "Full exercise object (with units) by id.",
1315
1387
  inputSchema: { id: idParam },
1388
+ outputSchema: toolOutputSchema(exerciseGetOutputSchema),
1316
1389
  annotations: READ
1317
1390
  }, ({ id }) => attempt(async () => {
1318
1391
  const ex = await index.get(toId(id));
@@ -1322,21 +1395,28 @@ function registerExerciseTools(server, ctx) {
1322
1395
  title: "Sync exercise library",
1323
1396
  description: "Refresh the cached exercise index from TrainHeroic.",
1324
1397
  inputSchema: { force: z.boolean().optional() },
1398
+ outputSchema: opaqueOutputSchema,
1325
1399
  annotations: SYNC
1326
1400
  }, ({ force }) => attempt(async () => {
1327
1401
  if (force ?? false) return jsonResult(await index.refresh());
1328
1402
  await index.ensureFresh();
1329
1403
  return jsonResult(await index.stats());
1330
1404
  }));
1405
+ }
1406
+ /**
1407
+ * Exercise library tools over the ExerciseIndex — a D1 mirror on the hosted server, an
1408
+ * on-disk/in-memory cache locally. The descriptions stay at the interface level so they
1409
+ * read correctly on both backends.
1410
+ */
1411
+ function registerExerciseTools(server, ctx) {
1412
+ const index = ctx.index;
1413
+ registerExerciseReads(server, index);
1331
1414
  server.registerTool("exercise_create", {
1332
1415
  title: "Create custom exercise",
1333
1416
  description: "Create a custom exercise (POST /2.0/coach/exercise/create) and write it through to the mirror. Body example: {\"title\":\"Sandbag Clean\",\"param_1_type\":3,\"param_2_type\":1}.",
1334
1417
  inputSchema: { exercise: exerciseCreateSchema },
1335
- annotations: {
1336
- readOnlyHint: false,
1337
- destructiveHint: false,
1338
- openWorldHint: true
1339
- }
1418
+ outputSchema: toolOutputSchema(exerciseCreatedOutputSchema),
1419
+ annotations: ADDITIVE
1340
1420
  }, ({ exercise }) => attempt(async () => jsonResult(await index.create(exercise))));
1341
1421
  registerExerciseUpdate(server, index);
1342
1422
  registerExerciseDelete(server, index);
@@ -1344,9 +1424,11 @@ function registerExerciseTools(server, ctx) {
1344
1424
  title: "Forget exercise (cache only)",
1345
1425
  description: "Remove an exercise from the local mirror only. Does not call TrainHeroic — use exercise_delete to delete the live custom exercise.",
1346
1426
  inputSchema: { id: idParam },
1427
+ outputSchema: toolOutputSchema(exerciseForgottenOutputSchema),
1347
1428
  annotations: {
1348
1429
  readOnlyHint: false,
1349
1430
  idempotentHint: true,
1431
+ destructiveHint: false,
1350
1432
  openWorldHint: false
1351
1433
  }
1352
1434
  }, ({ id }) => attempt(async () => {
@@ -1357,6 +1439,7 @@ function registerExerciseTools(server, ctx) {
1357
1439
  title: "Exercise index stats",
1358
1440
  description: "Row counts and sync state for the cached exercise index.",
1359
1441
  inputSchema: {},
1442
+ outputSchema: opaqueOutputSchema,
1360
1443
  annotations: READ
1361
1444
  }, () => attempt(async () => jsonResult(await index.stats())));
1362
1445
  }
@@ -1375,11 +1458,8 @@ function registerBuild(server, ctx) {
1375
1458
  blocks: z.array(blockSpecSchema),
1376
1459
  instruction: z.string().optional()
1377
1460
  },
1378
- annotations: {
1379
- readOnlyHint: false,
1380
- destructiveHint: false,
1381
- openWorldHint: true
1382
- }
1461
+ outputSchema: toolOutputSchema(workoutBuildOutputSchema),
1462
+ annotations: ADDITIVE
1383
1463
  }, ({ programId, athleteId, date, timelineDay, blocks, instruction }) => attempt(async () => {
1384
1464
  if (date === void 0 && timelineDay === void 0) return errorResult("Provide either date (YYYY-M-D) or timelineDay.");
1385
1465
  const resolveArgs = {};
@@ -1419,10 +1499,8 @@ function registerReadPublish(server, ctx) {
1419
1499
  date: z.string(),
1420
1500
  pwId: z.number()
1421
1501
  },
1422
- annotations: {
1423
- readOnlyHint: true,
1424
- openWorldHint: true
1425
- }
1502
+ outputSchema: toolOutputSchema(workoutReadOutputSchema),
1503
+ annotations: READ
1426
1504
  }, ({ programId, date, pwId }) => attempt(async () => jsonResult(await readSession(ctx.client, programId, parseWorkoutDate(date), pwId))));
1427
1505
  server.registerTool("workout_publish", {
1428
1506
  title: "Publish a session",
@@ -1433,11 +1511,8 @@ function registerReadPublish(server, ctx) {
1433
1511
  pwId: z.number(),
1434
1512
  confirm: z.boolean().optional()
1435
1513
  },
1436
- annotations: {
1437
- readOnlyHint: false,
1438
- destructiveHint: true,
1439
- openWorldHint: true
1440
- }
1514
+ outputSchema: toolOutputSchema(workoutPublishOutputSchema),
1515
+ annotations: DESTRUCTIVE
1441
1516
  }, ({ programId, date, pwId, confirm }, extra) => attempt(async () => {
1442
1517
  const blocked = confirmGate(extra, `Publish session ${pwId} on ${date}? This is athlete-facing and immediate.`, confirm);
1443
1518
  if (blocked) return blocked;
@@ -1459,11 +1534,8 @@ function registerLifecycle(server, ctx) {
1459
1534
  pwId: z.number(),
1460
1535
  confirm: z.boolean().optional()
1461
1536
  },
1462
- annotations: {
1463
- readOnlyHint: false,
1464
- destructiveHint: true,
1465
- openWorldHint: true
1466
- }
1537
+ outputSchema: toolOutputSchema(removedSessionOutputSchema),
1538
+ annotations: DESTRUCTIVE
1467
1539
  }, ({ programId, pwId, confirm }, extra) => attempt(async () => {
1468
1540
  const blocked = confirmGate(extra, `Delete session ${pwId}? This removes it from the live calendar and is hard to undo.`, confirm);
1469
1541
  if (blocked) return blocked;
@@ -1477,11 +1549,8 @@ function registerLifecycle(server, ctx) {
1477
1549
  pwId: z.number(),
1478
1550
  confirm: z.boolean().optional()
1479
1551
  },
1480
- annotations: {
1481
- readOnlyHint: false,
1482
- destructiveHint: true,
1483
- openWorldHint: true
1484
- }
1552
+ outputSchema: opaqueOutputSchema,
1553
+ annotations: DESTRUCTIVE
1485
1554
  }, ({ pwId, confirm }, extra) => attempt(async () => {
1486
1555
  const blocked = confirmGate(extra, `Unpublish session ${pwId}? Athletes will no longer see it.`, confirm);
1487
1556
  if (blocked) return blocked;
@@ -1495,11 +1564,8 @@ function registerLifecycle(server, ctx) {
1495
1564
  pwId: z.number(),
1496
1565
  toDate: z.string()
1497
1566
  },
1498
- annotations: {
1499
- readOnlyHint: false,
1500
- destructiveHint: false,
1501
- openWorldHint: true
1502
- }
1567
+ outputSchema: opaqueOutputSchema,
1568
+ annotations: ADDITIVE
1503
1569
  }, ({ toProgramId, pwId, toDate }) => attempt(async () => jsonResult(await copySession(ctx.client, {
1504
1570
  toProgramId,
1505
1571
  pwId,
@@ -1509,23 +1575,17 @@ function registerLifecycle(server, ctx) {
1509
1575
  title: "Save a session to the library",
1510
1576
  description: "Save an existing session as a reusable template in the session library (POST .../programWorkout/saveWorkoutAsTemplate/{workoutId}). Pass the workout_id.",
1511
1577
  inputSchema: { workoutId: z.number() },
1512
- annotations: {
1513
- readOnlyHint: false,
1514
- destructiveHint: false,
1515
- openWorldHint: true
1516
- }
1578
+ outputSchema: opaqueOutputSchema,
1579
+ annotations: ADDITIVE
1517
1580
  }, ({ workoutId }) => apiCall(ctx, "POST", `/2.0/coach/calendar/programWorkout/saveWorkoutAsTemplate/${workoutId}`));
1518
1581
  }
1519
1582
  function registerTemplateLibrary(server, ctx) {
1520
1583
  server.registerTool("session_template_create", {
1521
1584
  title: "Create a session template",
1522
1585
  description: "Create an empty reusable session template in the library (POST /v5/sessions/template). Distinct from session_save_as_template, which copies an existing session. Pass title and optional instruction.",
1523
- inputSchema: sessionTemplateCreateSchema,
1524
- annotations: {
1525
- readOnlyHint: false,
1526
- destructiveHint: false,
1527
- openWorldHint: true
1528
- }
1586
+ inputSchema: sessionTemplateCreateSchema.shape,
1587
+ outputSchema: toolOutputSchema(sessionTemplateCreatedOutputSchema),
1588
+ annotations: ADDITIVE
1529
1589
  }, ({ title, instruction }) => attempt(async () => jsonResult(await createSessionTemplate(ctx.client, definedProps({
1530
1590
  title,
1531
1591
  instruction
@@ -1537,6 +1597,7 @@ function registerTemplateLibrary(server, ctx) {
1537
1597
  id: idParam,
1538
1598
  confirm: z.boolean().optional()
1539
1599
  },
1600
+ outputSchema: opaqueOutputSchema,
1540
1601
  annotations: DESTRUCTIVE
1541
1602
  }, ({ id, confirm }, extra) => attempt(async () => {
1542
1603
  const templateId = toId(id);
@@ -1559,6 +1620,7 @@ function registerReads(server, ctx) {
1559
1620
  title: "List conversations (live)",
1560
1621
  description: "List chat streams (id, kind, title) live from the API; no setup needed. Use the id to read/draft/send.",
1561
1622
  inputSchema: {},
1623
+ outputSchema: opaqueOutputSchema,
1562
1624
  annotations: READ
1563
1625
  }, () => attempt(async () => {
1564
1626
  return jsonResult((await fetchStreams(ctx.client)).map(({ stream, kind }) => ({
@@ -1577,12 +1639,14 @@ function registerReads(server, ctx) {
1577
1639
  limit: z.number().int().positive().max(200).optional(),
1578
1640
  afterCommentId: idParam.optional()
1579
1641
  },
1642
+ outputSchema: opaqueOutputSchema,
1580
1643
  annotations: READ
1581
1644
  }, ({ streamId, limit, afterCommentId }) => attempt(async () => jsonResult(await readLive(ctx.client, toId(streamId), limit ?? 20, afterCommentId === void 0 ? void 0 : toId(afterCommentId)))));
1582
1645
  server.registerTool("message_draft", {
1583
1646
  title: "Draft a message (preview only)",
1584
1647
  description: "Preview the exact payload and target WITHOUT sending. Always safe.",
1585
1648
  inputSchema: commentDraftSchema.shape,
1649
+ outputSchema: toolOutputSchema(messageDraftOutputSchema),
1586
1650
  annotations: READ
1587
1651
  }, ({ streamId, text, replyTo }) => attempt(async () => {
1588
1652
  const id = toId(streamId);
@@ -1602,6 +1666,7 @@ function registerWrites(server, ctx) {
1602
1666
  ...commentDraftSchema.shape,
1603
1667
  confirm: z.boolean().optional()
1604
1668
  },
1669
+ outputSchema: toolOutputSchema(messageSentOutputSchema),
1605
1670
  annotations: DESTRUCTIVE
1606
1671
  }, ({ streamId, text, replyTo, confirm }, extra) => attempt(async () => {
1607
1672
  const id = toId(streamId);
@@ -1620,6 +1685,7 @@ function registerWrites(server, ctx) {
1620
1685
  commentId: idParam,
1621
1686
  confirm: z.boolean().optional()
1622
1687
  },
1688
+ outputSchema: toolOutputSchema(messageDeletedOutputSchema),
1623
1689
  annotations: DESTRUCTIVE
1624
1690
  }, ({ streamId, commentId, confirm }, extra) => attempt(async () => {
1625
1691
  const blocked = confirmGate(extra, `Delete comment ${toId(commentId)} from stream ${toId(streamId)}? Acts on the live account.`, confirm);
@@ -1650,4 +1716,4 @@ function registerCoachTools(server, ctx) {
1650
1716
  registerMessagingTools(server, ctx);
1651
1717
  }
1652
1718
  //#endregion
1653
- export { DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SERVER_INSTRUCTIONS, SYNC, apiCall, apiResponseResult, attempt, boundedSerialize, clipArray, confirmGate, errorResult, idParam, jsonResult, mapSessionExercises, registerAnalyticsTools, registerAthleteTools, registerAthleteTrainingTools, registerCoachTools, registerExerciseTools, registerMainLiftTools, registerMessagingTools, registerProgramTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };
1719
+ export { ADDITIVE, DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SERVER_INSTRUCTIONS, SYNC, apiCall, apiResponseResult, attempt, boundedSerialize, clipArray, confirmGate, errorResult, idParam, jsonResult, mapSessionExercises, registerAnalyticsTools, registerAthleteTools, registerAthleteTrainingTools, registerCoachTools, registerExerciseTools, registerMainLiftTools, registerMessagingTools, registerProgramTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/core",
3
- "version": "3.2.0",
3
+ "version": "3.3.1",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -25,8 +25,8 @@
25
25
  "@cfworker/json-schema": "^4.1.1",
26
26
  "@modelcontextprotocol/server": "2.0.0",
27
27
  "zod": "^4.4.3",
28
- "@trainheroic-unofficial/dto": "3.2.0",
29
- "@trainheroic-unofficial/js": "3.2.0"
28
+ "@trainheroic-unofficial/dto": "3.3.1",
29
+ "@trainheroic-unofficial/js": "3.3.1"
30
30
  },
31
31
  "devDependencies": {
32
32
  "@types/node": "^26.2.0",