@vibe-hero/server 0.1.0

package/dist/tools/submitAnswer.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @file Real `submit_answer` tool module — DETERMINISTIC + FREE-FORM paths
+ * (T032 deterministic, US-1; T048 free-form, US-4).
+ *
+ * The core scoring entry point. For a deterministic item (`multiple_choice` /
+ * `short_answer`) it: finds the live {@link QuizRecord} + catalog item by
+ * `quizId`/`itemId`, grades it in-engine via {@link gradeMultipleChoice} /
+ * {@link gradeShortAnswer} (FR-011, instant + reproducible — SC-004), updates the
+ * learner's Elo ability against the item's FIXED authored difficulty
+ * ({@link updateAbility}; item difficulty never self-updates — E3), and persists
+ * the result.
+ *
+ * Privacy (FR-018): the persisted {@link AnsweredItem} carries ONLY derived
+ * fields — `itemId`, `tier`, `difficulty`, `grade`, `score`,
+ * `gradedBy: "engine"`, `answeredAt`. The raw answer text / chosen id is used to
+ * grade and then DISCARDED; it never reaches disk. The continuous `score` drives
+ * the Elo update; the binary {@link Grade} is the projection persisted in
+ * history.
+ *
+ * Persistence (atomic, FR-023a): a single {@link updateProfile} read-modify-write
+ * appends the {@link AnsweredItem} to the matching {@link QuizRecord} and updates
+ * the {@link AbilityEstimate} (`value`, `itemsSeen++`, `lastAssessedAt`, push
+ * `itemId` to `lastItemIds`). Re-running on the same answer is naturally
+ * idempotent in grade (SC-004) though it appends another graded item — quiz
+ * sessions are append-only event logs.
+ *
+ * Graduation (T046, US-3): after the ability update, the PURE
+ * {@link evaluateGraduation} engine decides whether this graded item promotes
+ * the learner to the next tier (hysteresis band + `dwell` consecutive
+ * qualifying items — SC-014) or demotes/flags below the lower band (FR-008/009).
+ * The decision updates `profile.graduations[key]` and the dwell counter on the
+ * AbilityEstimate; on a promotion a proactive spaced {@link ReviewEntry} is
+ * enqueued (FR-010) so a one-time streak is later re-verified, and the
+ * `graduation` field is surfaced on the result so the host informs the user.
+ *
+ * Free-form path (T048, US-4): when the item is `free_form` and the input carries
+ * a per-criterion `verdict`, the host agent's verdict is scored by the PURE
+ * {@link scoreVerdict} against the item's MCP-supplied rubric — the MCP computes
+ * the score (fraction of criteria met) and derives the grade; the agent never
+ * returns a bare score/boolean (anti-gaming, FR-012/013). The graded result then
+ * flows through the SAME ability-update / persistence / graduation pipeline as a
+ * deterministic grade, recorded as `gradedBy: "host_agent"` with NO raw answer
+ * text (FR-018). The two paths cross-guard: a deterministic answer on a free-form
+ * item, or a free-form verdict on a deterministic item, is rejected with a clear
+ * error.
+ *
+ * Gated (FR-032): NOT exempt — the gate runs before this handler.
+ *
+ * Exposed as a `dirOverride`-closing factory mirroring `config.ts` / `status.ts`.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md
+ * (`submit_answer` deterministic + free-form paths), spec.md FR-005 / FR-011 /
+ * FR-012 / FR-013 / FR-018 / SC-004, data-model.md (AnsweredItem /
+ * AbilityEstimate), research.md (OD-002 / OD-005).
+ */
+import type { CatalogLoadResult } from "../catalog/loader.js";
+import { z } from "zod";
+import { type AnyToolModule } from "./types.js";
+/**
+ * Permissive OBJECT schema registered with the SDK. `submit_answer`'s contract
+ * input is a *union* (deterministic answer XOR free-form verdict) which has no
+ * single `.shape` for `registerTool`, so the wire schema is a superset:
+ * `quizId` + `itemId` required, `answer`/`verdict` optional. The handler
+ * re-validates against the authoritative {@link SubmitAnswerInputSchema} union
+ * (discriminated structurally) before grading — a malformed payload is rejected
+ * there, not silently mis-graded.
+ */
+export declare const SubmitAnswerToolInputSchema: z.ZodObject<{
+    quizId: z.ZodString;
+    itemId: z.ZodString;
+    answer: z.ZodOptional<z.ZodObject<{
+        choiceId: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        text?: string | undefined;
+        choiceId?: string | undefined;
+    }, {
+        text?: string | undefined;
+        choiceId?: string | undefined;
+    }>>;
+    verdict: z.ZodOptional<z.ZodObject<{
+        criteria: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            met: z.ZodBoolean;
+            justification: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            met: boolean;
+            justification: string;
+        }, {
+            id: string;
+            met: boolean;
+            justification: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        criteria: {
+            id: string;
+            met: boolean;
+            justification: string;
+        }[];
+    }, {
+        criteria: {
+            id: string;
+            met: boolean;
+            justification: string;
+        }[];
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    itemId: string;
+    quizId: string;
+    answer?: {
+        text?: string | undefined;
+        choiceId?: string | undefined;
+    } | undefined;
+    verdict?: {
+        criteria: {
+            id: string;
+            met: boolean;
+            justification: string;
+        }[];
+    } | undefined;
+}, {
+    itemId: string;
+    quizId: string;
+    answer?: {
+        text?: string | undefined;
+        choiceId?: string | undefined;
+    } | undefined;
+    verdict?: {
+        criteria: {
+            id: string;
+            met: boolean;
+            justification: string;
+        }[];
+    } | undefined;
+}>;
+/** Inferred wire-input type for `submit_answer` (permissive superset). */
+export type SubmitAnswerToolInput = z.infer<typeof SubmitAnswerToolInputSchema>;
+/**
+ * A catalog source: returns the loaded topics (+ any per-file errors). Defaults
+ * to {@link loadBundledCatalog}; tests inject a fixture-dir loader so grading can
+ * resolve a topic with ≥5 deterministic items without disturbing the shared
+ * bundled snapshot.
+ */
+export type CatalogLoader = () => CatalogLoadResult;
+/**
+ * Build the `submit_answer` tool module (US-1 deterministic + US-4 free-form).
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @param catalogLoader - Catalog source override (test seam); defaults to the
+ *   bundled snapshot {@link loadBundledCatalog}.
+ */
+export declare const makeSubmitAnswerTool: (dirOverride?: string, catalogLoader?: CatalogLoader) => AnyToolModule;
+/** Default `submit_answer` module (env / `~/.vibe-hero`), used by the registry. */
+export declare const submitAnswerTool: AnyToolModule;
+//# sourceMappingURL=submitAnswer.d.ts.map

package/dist/tools/submitAnswer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submitAnswer.d.ts","sourceRoot":"","sources":["../../src/tools/submitAnswer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAwB9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBtC,CAAC;AACH,0EAA0E;AAC1E,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AA0ShF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,iBAAiB,CAAC;AAiDpD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC/B,cAAc,MAAM,EACpB,gBAAe,aAAkC,KAChD,aAwEC,CAAC;AAEL,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,EAAE,aAAsC,CAAC"}

package/dist/tools/submitAnswer.js

@@ -0,0 +1,402 @@
+/**
+ * @file Real `submit_answer` tool module — DETERMINISTIC + FREE-FORM paths
+ * (T032 deterministic, US-1; T048 free-form, US-4).
+ *
+ * The core scoring entry point. For a deterministic item (`multiple_choice` /
+ * `short_answer`) it: finds the live {@link QuizRecord} + catalog item by
+ * `quizId`/`itemId`, grades it in-engine via {@link gradeMultipleChoice} /
+ * {@link gradeShortAnswer} (FR-011, instant + reproducible — SC-004), updates the
+ * learner's Elo ability against the item's FIXED authored difficulty
+ * ({@link updateAbility}; item difficulty never self-updates — E3), and persists
+ * the result.
+ *
+ * Privacy (FR-018): the persisted {@link AnsweredItem} carries ONLY derived
+ * fields — `itemId`, `tier`, `difficulty`, `grade`, `score`,
+ * `gradedBy: "engine"`, `answeredAt`. The raw answer text / chosen id is used to
+ * grade and then DISCARDED; it never reaches disk. The continuous `score` drives
+ * the Elo update; the binary {@link Grade} is the projection persisted in
+ * history.
+ *
+ * Persistence (atomic, FR-023a): a single {@link updateProfile} read-modify-write
+ * appends the {@link AnsweredItem} to the matching {@link QuizRecord} and updates
+ * the {@link AbilityEstimate} (`value`, `itemsSeen++`, `lastAssessedAt`, push
+ * `itemId` to `lastItemIds`). Re-running on the same answer is naturally
+ * idempotent in grade (SC-004) though it appends another graded item — quiz
+ * sessions are append-only event logs.
+ *
+ * Graduation (T046, US-3): after the ability update, the PURE
+ * {@link evaluateGraduation} engine decides whether this graded item promotes
+ * the learner to the next tier (hysteresis band + `dwell` consecutive
+ * qualifying items — SC-014) or demotes/flags below the lower band (FR-008/009).
+ * The decision updates `profile.graduations[key]` and the dwell counter on the
+ * AbilityEstimate; on a promotion a proactive spaced {@link ReviewEntry} is
+ * enqueued (FR-010) so a one-time streak is later re-verified, and the
+ * `graduation` field is surfaced on the result so the host informs the user.
+ *
+ * Free-form path (T048, US-4): when the item is `free_form` and the input carries
+ * a per-criterion `verdict`, the host agent's verdict is scored by the PURE
+ * {@link scoreVerdict} against the item's MCP-supplied rubric — the MCP computes
+ * the score (fraction of criteria met) and derives the grade; the agent never
+ * returns a bare score/boolean (anti-gaming, FR-012/013). The graded result then
+ * flows through the SAME ability-update / persistence / graduation pipeline as a
+ * deterministic grade, recorded as `gradedBy: "host_agent"` with NO raw answer
+ * text (FR-018). The two paths cross-guard: a deterministic answer on a free-form
+ * item, or a free-form verdict on a deterministic item, is rejected with a clear
+ * error.
+ *
+ * Gated (FR-032): NOT exempt — the gate runs before this handler.
+ *
+ * Exposed as a `dirOverride`-closing factory mirroring `config.ts` / `status.ts`.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md
+ * (`submit_answer` deterministic + free-form paths), spec.md FR-005 / FR-011 /
+ * FR-012 / FR-013 / FR-018 / SC-004, data-model.md (AnsweredItem /
+ * AbilityEstimate), research.md (OD-002 / OD-005).
+ */
+import { ASSESSMENT_CONFIG } from "../config.js";
+import { loadBundledCatalog } from "../catalog/bundled/index.js";
+import { updateAbility } from "../engine/elo.js";
+import { evaluateGraduation, } from "../engine/graduation.js";
+import { gradeMultipleChoice, gradeShortAnswer, toGrade, } from "../grading/deterministic.js";
+import { scoreVerdict } from "../grading/freeform.js";
+import { loadProfile, updateProfile } from "../profile/store.js";
+import { abilityKey } from "../schemas/common.js";
+import { z } from "zod";
+import { SubmitAnswerInputSchema, } from "../schemas/tools.js";
+import { defineTool } from "./types.js";
+/**
+ * Permissive OBJECT schema registered with the SDK. `submit_answer`'s contract
+ * input is a *union* (deterministic answer XOR free-form verdict) which has no
+ * single `.shape` for `registerTool`, so the wire schema is a superset:
+ * `quizId` + `itemId` required, `answer`/`verdict` optional. The handler
+ * re-validates against the authoritative {@link SubmitAnswerInputSchema} union
+ * (discriminated structurally) before grading — a malformed payload is rejected
+ * there, not silently mis-graded.
+ */
+export const SubmitAnswerToolInputSchema = z.object({
+    quizId: z.string(),
+    itemId: z.string(),
+    answer: z
+        .object({
+        choiceId: z.string().optional(),
+        text: z.string().optional(),
+    })
+        .optional(),
+    verdict: z
+        .object({
+        criteria: z.array(z.object({
+            id: z.string(),
+            met: z.boolean(),
+            justification: z.string(),
+        })),
+    })
+        .optional(),
+});
+/**
+ * A type guard for the deterministic input variant (carries `answer`, not
+ * `verdict`). Free-form verdicts route to the T048 path; until then they are
+ * rejected so a free-form answer never silently mis-grades.
+ */
+const isDeterministic = (input) => "answer" in input;
+/** Find the catalog item with `itemId` across all topics; returns its topic too. */
+const findItem = (topics, itemId) => {
+    for (const topic of topics) {
+        const item = topic.items.find((i) => i.id === itemId);
+        if (item !== undefined)
+            return { topic, item };
+    }
+    return undefined;
+};
+/**
+ * Grade a deterministic item, returning the continuous score plus (for MC) the
+ * authored correct choice id so the caller can surface `correctAnswer`.
+ *
+ * @throws {Error} if `item` is `free_form` — a deterministic answer was submitted
+ *   for a free-form item; the caller must send a per-criterion `verdict` instead
+ *   (cross-guard, T048).
+ */
+const gradeDeterministic = (item, answer) => {
+    switch (item.type) {
+        case "multiple_choice": {
+            const { score, correctChoiceId } = gradeMultipleChoice(item, answer.choiceId);
+            return { score, correctAnswer: correctChoiceId };
+        }
+        case "short_answer": {
+            const { score } = gradeShortAnswer(item, answer.text);
+            return { score };
+        }
+        case "free_form":
+            throw new Error(`submit_answer: item ${JSON.stringify(item.id)} is free_form; submit a per-criterion \`verdict\`, not a deterministic \`answer\` (T048)`);
+    }
+};
+/**
+ * Build the AnsweredItem persisted in history. Derived fields ONLY — never the
+ * raw answer text / chosen id / verdict justifications (FR-018). The item's
+ * authored `tier` + fixed `difficulty` are recorded so history is
+ * self-describing without re-joining the catalog. `gradedBy` records WHO graded:
+ * the engine (deterministic) or the host agent (free-form verdict).
+ */
+const buildAnsweredItem = (item, score, grade, gradedBy, answeredAt) => ({
+    itemId: item.id,
+    tier: item.tier,
+    difficulty: item.difficulty,
+    grade,
+    score,
+    gradedBy,
+    answeredAt,
+});
+/**
+ * Advance an ability estimate by one graded item: apply the Elo update against
+ * the item's fixed difficulty, stamp `lastAssessedAt`, and push the item id onto
+ * `lastItemIds` (so the next `start_quiz` avoids re-serving it). A cold estimate
+ * (no prior entry) starts from {@link ASSESSMENT_CONFIG.startingAbility} with
+ * zero items seen.
+ */
+const advanceEstimate = (prior, item, score, answeredAt) => {
+    const before = prior?.value ?? ASSESSMENT_CONFIG.startingAbility;
+    const itemsSeen = prior?.itemsSeen ?? 0;
+    const update = updateAbility(before, itemsSeen, item.difficulty, score);
+    return {
+        before,
+        estimate: {
+            value: update.value,
+            itemsSeen: update.itemsSeen,
+            lastAssessedAt: answeredAt,
+            lastItemIds: [...(prior?.lastItemIds ?? []), item.id],
+            // Carry the prior dwell forward unchanged here; the graduation step
+            // (applyGraduation) reads it, then overwrites with the engine's next
+            // dwell so the consecutive-streak counter advances/resets per item.
+            dwell: prior?.dwell ?? 0,
+        },
+    };
+};
+/**
+ * Apply the PURE graduation decision (T046, US-3) to one ability key inside the
+ * store transaction. Reads the just-updated ability + the prior dwell counter,
+ * asks {@link evaluateGraduation} for the decision, then returns the next
+ * `graduations[key]`, the dwell to persist on the estimate, and (on a
+ * promotion) a proactive spaced {@link ReviewEntry} to enqueue (FR-010).
+ *
+ * - On `"graduated"`: write a `current` graduation at the new tier and enqueue a
+ *   `reason: "spaced"` review one staleness window out (so a one-time streak is
+ *   later re-verified — durable-knowledge semantics).
+ * - On `"demoted"`: step the tier down and flag `due_for_review` (FR-009). No
+ *   spaced entry — the lapse path (status/standing, T046) owns lapsed entries.
+ * - On no change: leave the existing graduation untouched, but still persist the
+ *   engine's dwell so the consecutive streak carries across items.
+ *
+ * @returns The decision plus the derived graduation/dwell/review side-outputs.
+ */
+const applyGraduation = (key, newAbility, priorDwell, existing, answeredAt) => {
+    const currentTier = existing?.currentTier ?? 0;
+    const decision = evaluateGraduation({
+        ability: newAbility,
+        currentTier,
+        dwell: priorDwell,
+    });
+    if (decision.reason === "graduated") {
+        const dueAt = new Date(Date.parse(answeredAt) +
+            ASSESSMENT_CONFIG.stalenessWindowDays * 24 * 60 * 60 * 1000).toISOString();
+        return {
+            decision,
+            dwell: decision.dwell,
+            graduation: {
+                currentTier: decision.tier,
+                status: "current",
+                graduatedAt: answeredAt,
+                lastChangeReason: "graduated",
+            },
+            spacedReview: { key, dueAt, reason: "spaced" },
+        };
+    }
+    if (decision.reason === "demoted") {
+        return {
+            decision,
+            dwell: decision.dwell,
+            graduation: {
+                currentTier: decision.tier,
+                status: "due_for_review",
+                // Preserve the original graduation timestamp if we have one; this is an
+                // audit field, and a demotion is a status change, not a re-graduation.
+                graduatedAt: existing?.graduatedAt ?? answeredAt,
+                lastChangeReason: "demoted",
+            },
+        };
+    }
+    // No change: keep the existing graduation row but persist the (possibly
+    // advanced) dwell streak.
+    return { decision, dwell: decision.dwell, graduation: existing };
+};
+/**
+ * Project a {@link GraduationDecision} into the `submit_answer` result's
+ * `graduation` field `{ changed, tier?, status?, reason? }`. On a change the
+ * `status` reflects the resulting graduation state (`current` on promotion,
+ * `due_for_review` on demotion); `tier` is included only when the resulting tier
+ * is a real tier (100–500) — a demotion all the way to `0` (un-graduated) omits
+ * it, matching the result schema (`TierSchema.optional()`). A no-change decision
+ * reports `changed: false` and nothing else.
+ */
+const toGraduationResult = (decision) => {
+    if (!decision.changed)
+        return { changed: false };
+    const status = decision.reason === "graduated" ? "current" : "due_for_review";
+    const base = {
+        changed: true,
+        status,
+        ...(decision.reason !== null ? { reason: decision.reason } : {}),
+    };
+    return decision.tier === 0 ? base : { ...base, tier: decision.tier };
+};
+/**
+ * Apply a graded answer to the profile inside the store's atomic
+ * read-modify-write: append the {@link AnsweredItem} to the matching live
+ * {@link QuizRecord} (and roll its `abilityAfter`), and replace the
+ * {@link AbilityEstimate} for the quiz's key. Returns the new profile plus the
+ * before/after abilities for the tool result.
+ *
+ * @throws {Error} if no live (un-completed) quiz with `quizId` exists.
+ */
+const persistGrade = async (quizId, item, score, grade, gradedBy, answeredAt, dirOverride) => {
+    let outcome;
+    await updateProfile((current) => {
+        const recordIndex = current.quizHistory.findIndex((q) => q.id === quizId);
+        const record = current.quizHistory[recordIndex];
+        if (record === undefined) {
+            throw new Error(`submit_answer: no quiz session found for quizId ${JSON.stringify(quizId)}`);
+        }
+        if (record.completedAt !== undefined) {
+            throw new Error(`submit_answer: quiz ${JSON.stringify(quizId)} is already completed`);
+        }
+        const key = record.key;
+        const prior = current.abilities[key];
+        const { before, estimate } = advanceEstimate(prior, item, score, answeredAt);
+        // Graduation (T046): evaluate hysteresis/dwell against the JUST-updated
+        // ability, threading the prior dwell counter through the pure engine.
+        const grad = applyGraduation(key, estimate.value, prior?.dwell ?? 0, current.graduations[key], answeredAt);
+        // Persist the engine's next dwell on the estimate so the consecutive streak
+        // carries across submit_answer calls (advanceEstimate seeded it from prior).
+        const estimateWithDwell = { ...estimate, dwell: grad.dwell };
+        outcome = { before, after: estimate.value, decision: grad.decision };
+        const answered = buildAnsweredItem(item, score, grade, gradedBy, answeredAt);
+        const updatedRecord = {
+            ...record,
+            items: [...record.items, answered],
+            abilityAfter: estimate.value,
+        };
+        const quizHistory = [...current.quizHistory];
+        quizHistory[recordIndex] = updatedRecord;
+        const graduations = grad.graduation === undefined
+            ? current.graduations
+            : { ...current.graduations, [key]: grad.graduation };
+        // On promotion, enqueue a proactive spaced review (FR-010), de-duped by key
+        // so repeated promotions don't pile up duplicate spaced entries.
+        const reviewSchedule = grad.spacedReview === undefined
+            ? current.reviewSchedule
+            : [
+                ...current.reviewSchedule.filter((e) => !(e.key === key && e.reason === "spaced")),
+                grad.spacedReview,
+            ];
+        return {
+            ...current,
+            abilities: { ...current.abilities, [key]: estimateWithDwell },
+            graduations,
+            reviewSchedule,
+            quizHistory,
+        };
+    }, dirOverride);
+    if (outcome === undefined) {
+        // Unreachable: the transform either set `outcome` or threw above.
+        throw new Error("submit_answer: ability update did not run");
+    }
+    return outcome;
+};
+/**
+ * Grade one item, dispatching on the input variant AND cross-guarding against
+ * the item type (so a deterministic answer on a free-form item, or a free-form
+ * verdict on a deterministic item, is rejected — never silently mis-graded):
+ *
+ * - DETERMINISTIC input (`answer`) → {@link gradeDeterministic}; all-or-nothing
+ *   score graded `"engine"`. The `free_form` branch there throws the cross-guard.
+ * - FREE-FORM input (`verdict`) → the item MUST be `free_form` with a rubric;
+ *   the PURE {@link scoreVerdict} computes the fraction-met score + grade against
+ *   the MCP-supplied rubric (FR-012/013), graded `"host_agent"`. A bare/partial
+ *   verdict is rejected inside `scoreVerdict` (anti-gaming, E2).
+ */
+const gradeItem = (input, item) => {
+    if (isDeterministic(input)) {
+        const { score, correctAnswer } = gradeDeterministic(item, input.answer);
+        // Deterministic items are all-or-nothing: any threshold in (0,1] suffices.
+        // Use the free-form pass threshold so there is one "correct" definition.
+        const grade = toGrade(score, ASSESSMENT_CONFIG.freeFormPassThreshold);
+        return correctAnswer !== undefined
+            ? { score, grade, gradedBy: "engine", correctAnswer }
+            : { score, grade, gradedBy: "engine" };
+    }
+    // Free-form verdict path (T048): the item must be free_form with a rubric.
+    if (item.type !== "free_form" || item.rubric === undefined) {
+        throw new Error(`submit_answer: item ${JSON.stringify(item.id)} is not free_form; submit a deterministic \`answer\`, not a \`verdict\``);
+    }
+    // The MCP computes the score from the per-criterion verdict against its own
+    // rubric — the agent never returns a bare score/boolean (FR-012/013).
+    const { score, grade } = scoreVerdict(input.verdict, item.rubric);
+    return { score, grade, gradedBy: "host_agent" };
+};
+/**
+ * Build the `submit_answer` tool module (US-1 deterministic + US-4 free-form).
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @param catalogLoader - Catalog source override (test seam); defaults to the
+ *   bundled snapshot {@link loadBundledCatalog}.
+ */
+export const makeSubmitAnswerTool = (dirOverride, catalogLoader = loadBundledCatalog) => defineTool({
+    name: "submit_answer",
+    description: "Grade one quiz item (deterministic answer or free-form host verdict) and update ability.",
+    // The SDK needs an object schema; the handler re-validates against the real
+    // discriminated union below (the authoritative parse).
+    inputSchema: SubmitAnswerToolInputSchema,
+    handler: async (raw) => {
+        // Authoritative validation: deterministic answer XOR free-form verdict.
+        // A bare-boolean / shapeless verdict fails the union here (anti-gaming,
+        // E2) before it ever reaches grading.
+        const input = SubmitAnswerInputSchema.parse(raw);
+        // Resolve the quiz's topic key so we can find the item in catalog scope.
+        const profile = await loadProfile(dirOverride);
+        const record = profile.quizHistory.find((q) => q.id === input.quizId);
+        if (record === undefined) {
+            throw new Error(`submit_answer: no quiz session found for quizId ${JSON.stringify(input.quizId)}`);
+        }
+        const { topics } = catalogLoader();
+        const found = findItem(topics, input.itemId);
+        if (found === undefined) {
+            throw new Error(`submit_answer: no catalog item matches itemId ${JSON.stringify(input.itemId)}`);
+        }
+        const { topic, item } = found;
+        // Defensive: the item must belong to the quiz's topic.
+        if (abilityKey(topic.class, topic.id) !== record.key) {
+            throw new Error(`submit_answer: item ${JSON.stringify(input.itemId)} does not belong to quiz ${JSON.stringify(input.quizId)}`);
+        }
+        // Grade via the path matching the input + item type (deterministic engine
+        // or free-form host verdict); both yield a continuous score + binary grade.
+        const { score, grade, gradedBy, correctAnswer } = gradeItem(input, item);
+        const answeredAt = new Date().toISOString();
+        const { before, after, decision } = await persistGrade(input.quizId, item, score, grade, gradedBy, answeredAt, dirOverride);
+        const result = {
+            grade,
+            score,
+            guidance: item.guidance,
+            ability: { before, after },
+            // Surface the graduation outcome so the host can congratulate (on a
+            // promotion) or flag for review (on a demotion). When nothing changed we
+            // still report `changed: false` with the holding tier (US-3).
+            graduation: toGraduationResult(decision),
+        };
+        // Only surface the correct answer for MC (where `correctAnswer` is set);
+        // free-form items have no single key to reveal.
+        return correctAnswer !== undefined
+            ? { ...result, correctAnswer }
+            : result;
+    },
+});
+/** Default `submit_answer` module (env / `~/.vibe-hero`), used by the registry. */
+export const submitAnswerTool = makeSubmitAnswerTool();
+//# sourceMappingURL=submitAnswer.js.map

package/dist/tools/submitAnswer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submitAnswer.js","sourceRoot":"","sources":["../../src/tools/submitAnswer.ts"],"names":[],"mappings":"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"}

package/dist/tools/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @file Tool-registry contract shared by every MCP tool module (T020).
+ *
+ * Each tool lives in its own module exporting a {@link ToolModule}: a name, a
+ * human description, a Zod `inputSchema` (an *object* schema — `index.ts` passes
+ * its `.shape` to the SDK's `registerTool`), and a `handler`. The handler is the
+ * pure tool logic; `index.ts` wraps it with the setup gate and adapts its plain
+ * JSON result into the SDK's `CallToolResult` shape.
+ *
+ * Keeping the handler return type a plain JSON object (not a `CallToolResult`)
+ * means tool logic stays decoupled from the transport: tests call handlers
+ * directly and assert on the JSON, and later tasks can replace placeholder
+ * handlers without touching transport wiring.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md.
+ */
+import type { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * A tool's JSON result: any serializable object. Concrete tools narrow this to
+ * their contract's output schema (e.g. `GetConfigResult`); the registry keeps it
+ * open so all 10 modules share one shape.
+ */
+export type ToolResult = Record<string, unknown>;
+/** A tool handler: parsed+validated input in, JSON result out. */
+export type ToolHandler<Args> = (args: Args) => Promise<ToolResult>;
+/**
+ * One MCP tool definition. `inputSchema` is a Zod object schema; its `.shape`
+ * (a raw Zod shape, i.e. `Record<string, ZodType>`) is what the SDK's
+ * `registerTool` expects as `inputSchema`. The `Schema` generic ties the
+ * handler's argument to the schema's inferred type, so per-tool modules are
+ * fully typed at their definition site.
+ */
+export interface ToolModule<Schema extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
+    /** The tool's wire name (e.g. `"get_status"`). */
+    readonly name: string;
+    /** One-line description surfaced to the host agent. */
+    readonly description: string;
+    /** Zod object schema for the tool's input. */
+    readonly inputSchema: Schema;
+    /** Pure tool logic, operating on parsed input. */
+    readonly handler: ToolHandler<z.infer<Schema>>;
+}
+/**
+ * Schema-erased registry entry. The per-tool `Schema` generic makes precise
+ * {@link ToolModule} types mutually unassignable (the handler arg is
+ * contravariant), so the registry collection stores this widened form:
+ * `inputSchema` is a generic object schema and `handler` accepts `unknown`. The
+ * SDK validates input against the shape before our handler runs, so the handler
+ * may parse/narrow as needed; `index.ts` passes `unknown` straight through the
+ * gate to it.
+ */
+export interface AnyToolModule {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: z.ZodObject<z.ZodRawShape>;
+    readonly handler: ToolHandler<unknown>;
+}
+/**
+ * Adapt a typed {@link ToolModule} into a schema-erased {@link AnyToolModule}
+ * for the registry. The returned handler parses raw input through the module's
+ * `inputSchema` (so the typed handler always receives validated, narrowed args)
+ * and delegates. Placeholder handlers that ignore their input pass through
+ * unchanged.
+ *
+ * @param tool - A fully-typed tool module.
+ * @returns The erased registry entry.
+ */
+export declare const defineTool: <Schema extends z.ZodObject<z.ZodRawShape>>(tool: ToolModule<Schema>) => AnyToolModule;
+/**
+ * Adapt a plain JSON {@link ToolResult} into the SDK's `CallToolResult`.
+ *
+ * We populate both `content` (a JSON text block, the universally-readable form
+ * for hosts/tests with no output schema) and `structuredContent` (the same
+ * object, machine-readable). This keeps results inspectable without registering
+ * an output schema for every tool yet.
+ *
+ * @param result - The tool's JSON result.
+ * @returns A well-formed `CallToolResult`.
+ */
+export declare const toCallToolResult: (result: ToolResult) => CallToolResult;
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,kEAAkE;AAClE,MAAM,MAAM,WAAW,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU,CACzB,MAAM,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;IAEtE,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;CAChD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CACxC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EAClE,MAAM,UAAU,CAAC,MAAM,CAAC,KACvB,aAMD,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,UAAU,KAAG,cAGpD,CAAC"}