mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-15 23:12:04 +00:00
Each tool call now emits a running step as it starts and its final status as it settles: found with a server-counted number of readings, empty with the reason, or failed. The no-tools path shows one step for the record summary. Steps carry catalog labels rendered in the request language, closed-enum domains and windows, and integers only; a lab analyte, a value or a model-written argument never reaches one. At most twelve per turn. They persist on the provenance, so a reload shows the same list. The conversation window reaches the step so a call without a window names the one it actually read. The no-tools transcripts gain the summary step; a new transcript pins found, empty and failed steps ahead of the first token.
292 lines
9.8 KiB
TypeScript
292 lines
9.8 KiB
TypeScript
/**
|
|
* Live steps: one `CoachStep` per tool call, emitted as `step` frames while
|
|
* the turn runs and persisted on `metricSource.steps`.
|
|
*
|
|
* A step carries a catalog label key, the server-rendered label, the domain,
|
|
* the window and a server-counted number. Never free text, an analyte name
|
|
* or a health value: every field is either a closed enum member checked
|
|
* here, a catalog string rendered from those enums, or a non-negative
|
|
* integer the server counted. Nothing the model wrote and nothing the
|
|
* record holds as text can reach it, because nothing is copied through
|
|
* without passing one of those checks.
|
|
*/
|
|
import type { Locale } from "@/lib/i18n/config";
|
|
import { getServerTranslator } from "@/lib/i18n/server-translator";
|
|
import type { AiToolCall } from "@/lib/ai/types";
|
|
import {
|
|
coachScopeSourceSchema,
|
|
coachScopeWindowSchema,
|
|
type CoachResultGranularity,
|
|
type CoachResultPeriod,
|
|
type CoachScopeWindow,
|
|
type CoachStep,
|
|
type CoachStepDomain,
|
|
type CoachStepReason,
|
|
type CoachStepStatus,
|
|
} from "@/lib/ai/coach/types";
|
|
import {
|
|
COACH_STEP_LABEL_KEYS,
|
|
coachDomainLabelKey,
|
|
coachWindowLabelKey,
|
|
} from "@/lib/ai/coach/dialog-keys";
|
|
import type { CoachToolResult } from "@/lib/ai/coach/tools/executor";
|
|
import {
|
|
isCoachToolName,
|
|
type CoachToolName,
|
|
} from "@/lib/ai/coach/tools/definitions";
|
|
|
|
/** At most this many steps per turn; later calls run but show no step. */
|
|
export const MAX_TURN_STEPS = 12;
|
|
|
|
const SCOPE_SOURCES: ReadonlySet<string> = new Set(
|
|
coachScopeSourceSchema.options,
|
|
);
|
|
const WINDOWS: ReadonlySet<string> = new Set(coachScopeWindowSchema.options);
|
|
const PERIODS: ReadonlySet<string> = new Set<CoachResultPeriod>([
|
|
"current",
|
|
"previous",
|
|
"yearAgo",
|
|
]);
|
|
const GRANULARITIES: ReadonlySet<string> = new Set<CoachResultGranularity>([
|
|
"day",
|
|
"week",
|
|
"month",
|
|
]);
|
|
|
|
/**
|
|
* The domain each tool reads. `null` means the domain is the validated
|
|
* `metric` argument. A record keyed on the tool name, so a new tool does not
|
|
* compile until it says what it reads.
|
|
*/
|
|
const TOOL_DOMAIN: Readonly<Record<CoachToolName, CoachStepDomain | null>> = {
|
|
get_metric_series: null,
|
|
get_glucose_panel: "glucose",
|
|
get_sleep: "sleep",
|
|
get_medication_compliance: "compliance",
|
|
get_labs: "labs",
|
|
get_illness_recovery: "illness",
|
|
get_workouts: "workouts",
|
|
get_cycle: "cycle",
|
|
get_correlations: "correlations",
|
|
};
|
|
|
|
/**
|
|
* The window a tool reads when the call names none. `"fallback"` is the
|
|
* conversation's window (the executor's default); `null` is a read with no
|
|
* window at all. Labs read a fixed trailing year whatever the conversation
|
|
* says, so their step says that year rather than the conversation's window.
|
|
*/
|
|
const TOOL_WINDOW: Readonly<
|
|
Record<CoachToolName, CoachScopeWindow | "fallback" | null>
|
|
> = {
|
|
get_metric_series: "fallback",
|
|
get_glucose_panel: "fallback",
|
|
get_sleep: "fallback",
|
|
get_medication_compliance: "fallback",
|
|
get_labs: "lastYear",
|
|
get_illness_recovery: "fallback",
|
|
get_workouts: "fallback",
|
|
get_cycle: null,
|
|
get_correlations: null,
|
|
};
|
|
|
|
/**
|
|
* A miss reason from the executor, mapped onto the step. Anything not listed
|
|
* (a correlation reader's own "no pattern survived" code, a rows-exist-but-
|
|
* no-block verdict) is an empty step with no stated reason: saying "no
|
|
* readings" there would be false.
|
|
*/
|
|
const MISS: Readonly<
|
|
Record<string, { status: CoachStepStatus; reason?: CoachStepReason }>
|
|
> = {
|
|
no_data: { status: "empty", reason: "no_data" },
|
|
analyte_not_found: { status: "empty", reason: "no_data" },
|
|
outside_window: { status: "empty", reason: "outside_window" },
|
|
module_disabled: { status: "empty", reason: "module_disabled" },
|
|
retrieval_failed: { status: "failed", reason: "retrieval_failed" },
|
|
no_data_unconfirmed: { status: "failed", reason: "retrieval_failed" },
|
|
invalid_arguments: { status: "failed", reason: "invalid_arguments" },
|
|
unknown_tool: { status: "failed", reason: "invalid_arguments" },
|
|
unsupported_metric: { status: "failed", reason: "invalid_arguments" },
|
|
use_get_glucose_panel: { status: "failed", reason: "invalid_arguments" },
|
|
use_get_medication_compliance: {
|
|
status: "failed",
|
|
reason: "invalid_arguments",
|
|
},
|
|
};
|
|
|
|
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
}
|
|
|
|
/** A non-negative integer, or undefined. Never a float: a count, not a value. */
|
|
function asCount(value: unknown): number | undefined {
|
|
return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
|
|
? value
|
|
: undefined;
|
|
}
|
|
|
|
function pick<T extends string>(
|
|
allowed: ReadonlySet<string>,
|
|
value: unknown,
|
|
): T | undefined {
|
|
return typeof value === "string" && allowed.has(value)
|
|
? (value as T)
|
|
: undefined;
|
|
}
|
|
|
|
/**
|
|
* How many readings or rows a present result covered, when the result says
|
|
* so in a field the server counted:
|
|
* - a metric series: the aggregate's coverage count;
|
|
* - workouts: the sessions in the window;
|
|
* - labs: the biomarkers returned (one row each).
|
|
* Anything else carries no count rather than a guess.
|
|
*/
|
|
function presentCount(tool: CoachToolName, data: unknown): number | undefined {
|
|
if (!isRecord(data)) return undefined;
|
|
switch (tool) {
|
|
case "get_metric_series": {
|
|
const section = data.section;
|
|
if (!isRecord(section) || !isRecord(section.aggregate)) return undefined;
|
|
const coverage = section.aggregate.coverage;
|
|
return isRecord(coverage) ? asCount(coverage.count) : undefined;
|
|
}
|
|
case "get_workouts":
|
|
return asCount(data.totalInWindow);
|
|
case "get_labs":
|
|
return Array.isArray(data.recent) ? data.recent.length : undefined;
|
|
default:
|
|
return undefined;
|
|
}
|
|
}
|
|
|
|
function render(
|
|
locale: Locale,
|
|
domain: CoachStepDomain,
|
|
window: CoachScopeWindow | undefined,
|
|
): { labelKey: string; label: string } {
|
|
const { t } = getServerTranslator(locale);
|
|
const labelKey = window
|
|
? COACH_STEP_LABEL_KEYS.readWindow
|
|
: COACH_STEP_LABEL_KEYS.read;
|
|
return {
|
|
labelKey,
|
|
label: t(labelKey, {
|
|
domain: t(coachDomainLabelKey(domain)),
|
|
...(window ? { window: t(coachWindowLabelKey(window)) } : {}),
|
|
}),
|
|
};
|
|
}
|
|
|
|
/**
|
|
* The step for one tool call: `running` when `result` is absent (the call
|
|
* just started), its final status once the result is in. `index` counts
|
|
* calls across the turn from 0; `parsedArgs` are the schema-validated
|
|
* arguments, absent when they did not validate. `fallbackWindow` is the
|
|
* conversation's window, the one a call without a window reads.
|
|
*
|
|
* Null for a call past the cap, for a tool name outside the catalogue, and
|
|
* for a metric call whose metric did not validate: there is nothing true to
|
|
* label those with.
|
|
*/
|
|
export function toStep(args: {
|
|
call: AiToolCall;
|
|
index: number;
|
|
parsedArgs: Record<string, unknown> | undefined;
|
|
result?: CoachToolResult;
|
|
locale: Locale;
|
|
fallbackWindow?: CoachScopeWindow;
|
|
}): CoachStep | null {
|
|
const { call, index, parsedArgs, result, locale } = args;
|
|
if (!Number.isSafeInteger(index) || index < 0 || index >= MAX_TURN_STEPS) {
|
|
return null;
|
|
}
|
|
if (!isCoachToolName(call.name)) return null;
|
|
const tool = call.name;
|
|
|
|
const domain =
|
|
TOOL_DOMAIN[tool] ??
|
|
pick<CoachStepDomain>(SCOPE_SOURCES, parsedArgs?.metric);
|
|
// A metric series call whose arguments did not validate names no domain
|
|
// the executor would read; the executor refuses it and the model is told.
|
|
// There is nothing true to show, so it gets no step.
|
|
if (!domain) return null;
|
|
|
|
const windowRule = TOOL_WINDOW[tool];
|
|
const window =
|
|
windowRule === null
|
|
? undefined
|
|
: windowRule === "fallback"
|
|
? (pick<CoachScopeWindow>(WINDOWS, parsedArgs?.window) ??
|
|
pick<CoachScopeWindow>(WINDOWS, result?.searchedWindow) ??
|
|
pick<CoachScopeWindow>(WINDOWS, args.fallbackWindow))
|
|
: windowRule;
|
|
const period = pick<CoachResultPeriod>(PERIODS, parsedArgs?.period);
|
|
const granularity = pick<CoachResultGranularity>(
|
|
GRANULARITIES,
|
|
parsedArgs?.granularity,
|
|
);
|
|
|
|
const settled = settle(tool, result);
|
|
return {
|
|
id: `s${index + 1}`,
|
|
tool,
|
|
...render(locale, domain, window),
|
|
domain,
|
|
...(window ? { window } : {}),
|
|
...(period ? { period } : {}),
|
|
...(granularity ? { granularity } : {}),
|
|
status: settled.status,
|
|
...(settled.count !== undefined ? { count: settled.count } : {}),
|
|
...(settled.reason ? { reason: settled.reason } : {}),
|
|
};
|
|
}
|
|
|
|
function settle(
|
|
tool: CoachToolName,
|
|
result: CoachToolResult | undefined,
|
|
): { status: CoachStepStatus; count?: number; reason?: CoachStepReason } {
|
|
if (!result) return { status: "running" };
|
|
if (result.present) {
|
|
return { status: "done", count: presentCount(tool, result.data) };
|
|
}
|
|
const miss = (typeof result.reason === "string" &&
|
|
Object.hasOwn(MISS, result.reason) &&
|
|
MISS[result.reason]) || { status: "empty" as const };
|
|
// An out-of-window miss knows how much the record holds elsewhere; the
|
|
// count rides the step for the method line, the row shows the reason.
|
|
const count =
|
|
miss.status === "empty" && isRecord(result.available)
|
|
? asCount(result.available.count)
|
|
: undefined;
|
|
return {
|
|
status: miss.status,
|
|
...(count !== undefined ? { count } : {}),
|
|
...(miss.reason ? { reason: miss.reason } : {}),
|
|
};
|
|
}
|
|
|
|
/**
|
|
* The single step a no-tools turn shows: the full snapshot, with the number
|
|
* of metrics it covered. The snapshot is already built when this runs, so
|
|
* the step is settled from the start.
|
|
*/
|
|
export function snapshotStep(args: {
|
|
metricCount: number;
|
|
locale: Locale;
|
|
}): CoachStep | null {
|
|
const { t } = getServerTranslator(args.locale);
|
|
const count = asCount(args.metricCount) ?? 0;
|
|
return {
|
|
id: "s1",
|
|
tool: "snapshot",
|
|
labelKey: COACH_STEP_LABEL_KEYS.snapshot,
|
|
label: t(COACH_STEP_LABEL_KEYS.snapshot),
|
|
domain: "snapshot",
|
|
status: count > 0 ? "done" : "empty",
|
|
count,
|
|
...(count === 0 ? { reason: "no_data" as const } : {}),
|
|
};
|
|
}
|