@trainheroic-unofficial/core 3.2.0 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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,7 +1165,8 @@ 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",
@@ -1111,7 +1176,8 @@ function registerTeamTools(server, ctx) {
1111
1176
  title: z.string().min(1).optional(),
1112
1177
  groupProgram: idParam.optional()
1113
1178
  },
1114
- annotations: ADDITIVE$1
1179
+ outputSchema: opaqueOutputSchema,
1180
+ annotations: ADDITIVE
1115
1181
  }, ({ teamId, title, groupProgram }) => attempt(async () => {
1116
1182
  const args = { teamId: toId(teamId) };
1117
1183
  if (title !== void 0) args.title = title;
@@ -1125,6 +1191,7 @@ function registerTeamTools(server, ctx) {
1125
1191
  teamId: idParam,
1126
1192
  confirm: z.boolean().optional()
1127
1193
  },
1194
+ outputSchema: opaqueOutputSchema,
1128
1195
  annotations: DESTRUCTIVE
1129
1196
  }, ({ teamId, confirm }, extra) => attempt(async () => {
1130
1197
  const id = toId(teamId);
@@ -1139,7 +1206,8 @@ function registerTeamTools(server, ctx) {
1139
1206
  teamId: idParam,
1140
1207
  type: z.number().int().optional()
1141
1208
  },
1142
- annotations: ADDITIVE$1
1209
+ outputSchema: opaqueOutputSchema,
1210
+ annotations: ADDITIVE
1143
1211
  }, ({ teamId, type }) => apiCall(ctx, "POST", `/v5/teams/${toId(teamId)}/teamCodes`, { body: { type: type ?? 2 } }));
1144
1212
  server.registerTool("team_code_delete", {
1145
1213
  title: "Delete a team join code",
@@ -1148,6 +1216,7 @@ function registerTeamTools(server, ctx) {
1148
1216
  codeId: idParam,
1149
1217
  confirm: z.boolean().optional()
1150
1218
  },
1219
+ outputSchema: opaqueOutputSchema,
1151
1220
  annotations: DESTRUCTIVE
1152
1221
  }, ({ codeId, confirm }, extra) => attempt(async () => {
1153
1222
  const id = toId(codeId);
@@ -1167,6 +1236,7 @@ function registerTeamPublishSettings(server, ctx) {
1167
1236
  ...teamPublishPatchObject.shape,
1168
1237
  confirm: z.boolean().optional()
1169
1238
  },
1239
+ outputSchema: opaqueOutputSchema,
1170
1240
  annotations: DESTRUCTIVE
1171
1241
  }, ({ teamId, programId, pub_enabled, pub_days, pub_time, pub_timezone, confirm }, extra) => attempt(async () => {
1172
1242
  const blocked = confirmGate(extra, "Change auto-publish settings? This controls when athletes see programmed sessions.", confirm);
@@ -1189,11 +1259,6 @@ function registerTeamPublishSettings(server, ctx) {
1189
1259
  }
1190
1260
  //#endregion
1191
1261
  //#region src/tools/programs.ts
1192
- const ADDITIVE = {
1193
- readOnlyHint: false,
1194
- destructiveHint: false,
1195
- openWorldHint: true
1196
- };
1197
1262
  /** Standalone program writes. Program reads live in reads.ts. */
1198
1263
  function registerProgramTools(server, ctx) {
1199
1264
  server.registerTool("program_create", {
@@ -1203,6 +1268,7 @@ function registerProgramTools(server, ctx) {
1203
1268
  kind: z.enum(PROGRAM_KINDS),
1204
1269
  name: z.string().trim().min(1)
1205
1270
  },
1271
+ outputSchema: toolOutputSchema(programCreatedOutputSchema),
1206
1272
  annotations: ADDITIVE
1207
1273
  }, ({ kind, name }) => attempt(async () => jsonResult(await createProgram(ctx.client, {
1208
1274
  kind,
@@ -1215,6 +1281,7 @@ function registerProgramTools(server, ctx) {
1215
1281
  programId: idParam,
1216
1282
  confirm: z.boolean().optional()
1217
1283
  },
1284
+ outputSchema: toolOutputSchema(programDeletedOutputSchema),
1218
1285
  annotations: DESTRUCTIVE
1219
1286
  }, ({ programId, confirm }, extra) => attempt(async () => {
1220
1287
  const id = toId(programId);
@@ -1241,6 +1308,7 @@ function registerAnalyticsTools(server, ctx) {
1241
1308
  dateEnd: z.string().optional(),
1242
1309
  useMetric: z.boolean().optional()
1243
1310
  },
1311
+ outputSchema: opaqueOutputSchema,
1244
1312
  annotations: READ
1245
1313
  }, ({ metric, teamId, userIds, exerciseId, date, dateStart, dateEnd, useMetric }) => attempt(async () => jsonResult(await queryAnalytics(ctx.client, definedProps({
1246
1314
  metric,
@@ -1263,11 +1331,8 @@ function registerExerciseUpdate(server, index) {
1263
1331
  id: idParam,
1264
1332
  exercise: exerciseCreateSchema
1265
1333
  },
1266
- annotations: {
1267
- readOnlyHint: false,
1268
- destructiveHint: false,
1269
- openWorldHint: true
1270
- }
1334
+ outputSchema: toolOutputSchema(exerciseCreatedOutputSchema),
1335
+ annotations: ADDITIVE
1271
1336
  }, ({ id, exercise }) => attempt(async () => jsonResult(await index.update(toId(id), exercise))));
1272
1337
  }
1273
1338
  function registerExerciseDelete(server, index) {
@@ -1278,6 +1343,7 @@ function registerExerciseDelete(server, index) {
1278
1343
  id: idParam,
1279
1344
  confirm: z.boolean().optional()
1280
1345
  },
1346
+ outputSchema: toolOutputSchema(exerciseDeletedOutputSchema),
1281
1347
  annotations: DESTRUCTIVE
1282
1348
  }, ({ id, confirm }, extra) => attempt(async () => {
1283
1349
  const exerciseId = toId(id);
@@ -1287,17 +1353,12 @@ function registerExerciseDelete(server, index) {
1287
1353
  return jsonResult({ deleted: exerciseId });
1288
1354
  }));
1289
1355
  }
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;
1356
+ function registerExerciseReads(server, index) {
1297
1357
  server.registerTool("exercise_resolve", {
1298
1358
  title: "Resolve exercise name",
1299
1359
  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
1360
  inputSchema: { name: z.string().min(1) },
1361
+ outputSchema: toolOutputSchema(exerciseResolveOutputSchema),
1301
1362
  annotations: READ
1302
1363
  }, ({ name }) => attempt(async () => jsonResult(await index.resolve(name))));
1303
1364
  server.registerTool("exercise_search", {
@@ -1307,12 +1368,14 @@ function registerExerciseTools(server, ctx) {
1307
1368
  query: z.string().min(1),
1308
1369
  limit: z.number().int().positive().max(100).optional()
1309
1370
  },
1371
+ outputSchema: toolOutputSchema(z.array(exerciseViewSchema)),
1310
1372
  annotations: READ
1311
1373
  }, ({ query, limit }) => attempt(async () => jsonResult(await index.search(query, limit ?? 20))));
1312
1374
  server.registerTool("exercise_get", {
1313
1375
  title: "Get exercise",
1314
1376
  description: "Full exercise object (with units) by id.",
1315
1377
  inputSchema: { id: idParam },
1378
+ outputSchema: toolOutputSchema(exerciseGetOutputSchema),
1316
1379
  annotations: READ
1317
1380
  }, ({ id }) => attempt(async () => {
1318
1381
  const ex = await index.get(toId(id));
@@ -1322,21 +1385,28 @@ function registerExerciseTools(server, ctx) {
1322
1385
  title: "Sync exercise library",
1323
1386
  description: "Refresh the cached exercise index from TrainHeroic.",
1324
1387
  inputSchema: { force: z.boolean().optional() },
1388
+ outputSchema: opaqueOutputSchema,
1325
1389
  annotations: SYNC
1326
1390
  }, ({ force }) => attempt(async () => {
1327
1391
  if (force ?? false) return jsonResult(await index.refresh());
1328
1392
  await index.ensureFresh();
1329
1393
  return jsonResult(await index.stats());
1330
1394
  }));
1395
+ }
1396
+ /**
1397
+ * Exercise library tools over the ExerciseIndex — a D1 mirror on the hosted server, an
1398
+ * on-disk/in-memory cache locally. The descriptions stay at the interface level so they
1399
+ * read correctly on both backends.
1400
+ */
1401
+ function registerExerciseTools(server, ctx) {
1402
+ const index = ctx.index;
1403
+ registerExerciseReads(server, index);
1331
1404
  server.registerTool("exercise_create", {
1332
1405
  title: "Create custom exercise",
1333
1406
  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
1407
  inputSchema: { exercise: exerciseCreateSchema },
1335
- annotations: {
1336
- readOnlyHint: false,
1337
- destructiveHint: false,
1338
- openWorldHint: true
1339
- }
1408
+ outputSchema: toolOutputSchema(exerciseCreatedOutputSchema),
1409
+ annotations: ADDITIVE
1340
1410
  }, ({ exercise }) => attempt(async () => jsonResult(await index.create(exercise))));
1341
1411
  registerExerciseUpdate(server, index);
1342
1412
  registerExerciseDelete(server, index);
@@ -1344,9 +1414,11 @@ function registerExerciseTools(server, ctx) {
1344
1414
  title: "Forget exercise (cache only)",
1345
1415
  description: "Remove an exercise from the local mirror only. Does not call TrainHeroic — use exercise_delete to delete the live custom exercise.",
1346
1416
  inputSchema: { id: idParam },
1417
+ outputSchema: toolOutputSchema(exerciseForgottenOutputSchema),
1347
1418
  annotations: {
1348
1419
  readOnlyHint: false,
1349
1420
  idempotentHint: true,
1421
+ destructiveHint: false,
1350
1422
  openWorldHint: false
1351
1423
  }
1352
1424
  }, ({ id }) => attempt(async () => {
@@ -1357,6 +1429,7 @@ function registerExerciseTools(server, ctx) {
1357
1429
  title: "Exercise index stats",
1358
1430
  description: "Row counts and sync state for the cached exercise index.",
1359
1431
  inputSchema: {},
1432
+ outputSchema: opaqueOutputSchema,
1360
1433
  annotations: READ
1361
1434
  }, () => attempt(async () => jsonResult(await index.stats())));
1362
1435
  }
@@ -1375,11 +1448,8 @@ function registerBuild(server, ctx) {
1375
1448
  blocks: z.array(blockSpecSchema),
1376
1449
  instruction: z.string().optional()
1377
1450
  },
1378
- annotations: {
1379
- readOnlyHint: false,
1380
- destructiveHint: false,
1381
- openWorldHint: true
1382
- }
1451
+ outputSchema: toolOutputSchema(workoutBuildOutputSchema),
1452
+ annotations: ADDITIVE
1383
1453
  }, ({ programId, athleteId, date, timelineDay, blocks, instruction }) => attempt(async () => {
1384
1454
  if (date === void 0 && timelineDay === void 0) return errorResult("Provide either date (YYYY-M-D) or timelineDay.");
1385
1455
  const resolveArgs = {};
@@ -1419,10 +1489,8 @@ function registerReadPublish(server, ctx) {
1419
1489
  date: z.string(),
1420
1490
  pwId: z.number()
1421
1491
  },
1422
- annotations: {
1423
- readOnlyHint: true,
1424
- openWorldHint: true
1425
- }
1492
+ outputSchema: toolOutputSchema(workoutReadOutputSchema),
1493
+ annotations: READ
1426
1494
  }, ({ programId, date, pwId }) => attempt(async () => jsonResult(await readSession(ctx.client, programId, parseWorkoutDate(date), pwId))));
1427
1495
  server.registerTool("workout_publish", {
1428
1496
  title: "Publish a session",
@@ -1433,11 +1501,8 @@ function registerReadPublish(server, ctx) {
1433
1501
  pwId: z.number(),
1434
1502
  confirm: z.boolean().optional()
1435
1503
  },
1436
- annotations: {
1437
- readOnlyHint: false,
1438
- destructiveHint: true,
1439
- openWorldHint: true
1440
- }
1504
+ outputSchema: toolOutputSchema(workoutPublishOutputSchema),
1505
+ annotations: DESTRUCTIVE
1441
1506
  }, ({ programId, date, pwId, confirm }, extra) => attempt(async () => {
1442
1507
  const blocked = confirmGate(extra, `Publish session ${pwId} on ${date}? This is athlete-facing and immediate.`, confirm);
1443
1508
  if (blocked) return blocked;
@@ -1459,11 +1524,8 @@ function registerLifecycle(server, ctx) {
1459
1524
  pwId: z.number(),
1460
1525
  confirm: z.boolean().optional()
1461
1526
  },
1462
- annotations: {
1463
- readOnlyHint: false,
1464
- destructiveHint: true,
1465
- openWorldHint: true
1466
- }
1527
+ outputSchema: toolOutputSchema(removedSessionOutputSchema),
1528
+ annotations: DESTRUCTIVE
1467
1529
  }, ({ programId, pwId, confirm }, extra) => attempt(async () => {
1468
1530
  const blocked = confirmGate(extra, `Delete session ${pwId}? This removes it from the live calendar and is hard to undo.`, confirm);
1469
1531
  if (blocked) return blocked;
@@ -1477,11 +1539,8 @@ function registerLifecycle(server, ctx) {
1477
1539
  pwId: z.number(),
1478
1540
  confirm: z.boolean().optional()
1479
1541
  },
1480
- annotations: {
1481
- readOnlyHint: false,
1482
- destructiveHint: true,
1483
- openWorldHint: true
1484
- }
1542
+ outputSchema: opaqueOutputSchema,
1543
+ annotations: DESTRUCTIVE
1485
1544
  }, ({ pwId, confirm }, extra) => attempt(async () => {
1486
1545
  const blocked = confirmGate(extra, `Unpublish session ${pwId}? Athletes will no longer see it.`, confirm);
1487
1546
  if (blocked) return blocked;
@@ -1495,11 +1554,8 @@ function registerLifecycle(server, ctx) {
1495
1554
  pwId: z.number(),
1496
1555
  toDate: z.string()
1497
1556
  },
1498
- annotations: {
1499
- readOnlyHint: false,
1500
- destructiveHint: false,
1501
- openWorldHint: true
1502
- }
1557
+ outputSchema: opaqueOutputSchema,
1558
+ annotations: ADDITIVE
1503
1559
  }, ({ toProgramId, pwId, toDate }) => attempt(async () => jsonResult(await copySession(ctx.client, {
1504
1560
  toProgramId,
1505
1561
  pwId,
@@ -1509,23 +1565,17 @@ function registerLifecycle(server, ctx) {
1509
1565
  title: "Save a session to the library",
1510
1566
  description: "Save an existing session as a reusable template in the session library (POST .../programWorkout/saveWorkoutAsTemplate/{workoutId}). Pass the workout_id.",
1511
1567
  inputSchema: { workoutId: z.number() },
1512
- annotations: {
1513
- readOnlyHint: false,
1514
- destructiveHint: false,
1515
- openWorldHint: true
1516
- }
1568
+ outputSchema: opaqueOutputSchema,
1569
+ annotations: ADDITIVE
1517
1570
  }, ({ workoutId }) => apiCall(ctx, "POST", `/2.0/coach/calendar/programWorkout/saveWorkoutAsTemplate/${workoutId}`));
1518
1571
  }
1519
1572
  function registerTemplateLibrary(server, ctx) {
1520
1573
  server.registerTool("session_template_create", {
1521
1574
  title: "Create a session template",
1522
1575
  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
- }
1576
+ inputSchema: sessionTemplateCreateSchema.shape,
1577
+ outputSchema: toolOutputSchema(sessionTemplateCreatedOutputSchema),
1578
+ annotations: ADDITIVE
1529
1579
  }, ({ title, instruction }) => attempt(async () => jsonResult(await createSessionTemplate(ctx.client, definedProps({
1530
1580
  title,
1531
1581
  instruction
@@ -1537,6 +1587,7 @@ function registerTemplateLibrary(server, ctx) {
1537
1587
  id: idParam,
1538
1588
  confirm: z.boolean().optional()
1539
1589
  },
1590
+ outputSchema: opaqueOutputSchema,
1540
1591
  annotations: DESTRUCTIVE
1541
1592
  }, ({ id, confirm }, extra) => attempt(async () => {
1542
1593
  const templateId = toId(id);
@@ -1559,6 +1610,7 @@ function registerReads(server, ctx) {
1559
1610
  title: "List conversations (live)",
1560
1611
  description: "List chat streams (id, kind, title) live from the API; no setup needed. Use the id to read/draft/send.",
1561
1612
  inputSchema: {},
1613
+ outputSchema: opaqueOutputSchema,
1562
1614
  annotations: READ
1563
1615
  }, () => attempt(async () => {
1564
1616
  return jsonResult((await fetchStreams(ctx.client)).map(({ stream, kind }) => ({
@@ -1577,12 +1629,14 @@ function registerReads(server, ctx) {
1577
1629
  limit: z.number().int().positive().max(200).optional(),
1578
1630
  afterCommentId: idParam.optional()
1579
1631
  },
1632
+ outputSchema: opaqueOutputSchema,
1580
1633
  annotations: READ
1581
1634
  }, ({ streamId, limit, afterCommentId }) => attempt(async () => jsonResult(await readLive(ctx.client, toId(streamId), limit ?? 20, afterCommentId === void 0 ? void 0 : toId(afterCommentId)))));
1582
1635
  server.registerTool("message_draft", {
1583
1636
  title: "Draft a message (preview only)",
1584
1637
  description: "Preview the exact payload and target WITHOUT sending. Always safe.",
1585
1638
  inputSchema: commentDraftSchema.shape,
1639
+ outputSchema: toolOutputSchema(messageDraftOutputSchema),
1586
1640
  annotations: READ
1587
1641
  }, ({ streamId, text, replyTo }) => attempt(async () => {
1588
1642
  const id = toId(streamId);
@@ -1602,6 +1656,7 @@ function registerWrites(server, ctx) {
1602
1656
  ...commentDraftSchema.shape,
1603
1657
  confirm: z.boolean().optional()
1604
1658
  },
1659
+ outputSchema: toolOutputSchema(messageSentOutputSchema),
1605
1660
  annotations: DESTRUCTIVE
1606
1661
  }, ({ streamId, text, replyTo, confirm }, extra) => attempt(async () => {
1607
1662
  const id = toId(streamId);
@@ -1620,6 +1675,7 @@ function registerWrites(server, ctx) {
1620
1675
  commentId: idParam,
1621
1676
  confirm: z.boolean().optional()
1622
1677
  },
1678
+ outputSchema: toolOutputSchema(messageDeletedOutputSchema),
1623
1679
  annotations: DESTRUCTIVE
1624
1680
  }, ({ streamId, commentId, confirm }, extra) => attempt(async () => {
1625
1681
  const blocked = confirmGate(extra, `Delete comment ${toId(commentId)} from stream ${toId(streamId)}? Acts on the live account.`, confirm);
@@ -1650,4 +1706,4 @@ function registerCoachTools(server, ctx) {
1650
1706
  registerMessagingTools(server, ctx);
1651
1707
  }
1652
1708
  //#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 };
1709
+ 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.0",
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.0",
29
+ "@trainheroic-unofficial/js": "3.3.0"
30
30
  },
31
31
  "devDependencies": {
32
32
  "@types/node": "^26.2.0",