@vibe-hero/server 0.1.0

package/dist/tools/guidance.js

@@ -0,0 +1,117 @@
+/**
+ * @file Real `get_guidance` tool module (T027, US-2).
+ *
+ * Returns teaching guidance plus a concrete next step for a topic. Given a `key`
+ * it guides on that exact `(topic × class)`; with NO `key` it auto-selects the
+ * learner's weakest/stale in-scope topic (the same weakness ranking
+ * `get_status` uses for `suggestions`) so "what should I learn next?" resolves
+ * without the user naming a topic.
+ *
+ * Guidance text is pulled from the topic's authored content: the `guidance` of
+ * an item at — or, failing that, nearest above — the learner's current tier,
+ * falling back to the topic `summary` when the topic has no items. The next step
+ * is a `quiz` when the topic has gradeable items (the practice path, FR-021),
+ * else a `read` nudge toward the summary.
+ *
+ * Telemetry-free (SC-011): everything is derived from the bundled catalog + the
+ * profile's `abilities`/`graduations`; no observation/offer state is read.
+ * Gated (FR-032) — `index.ts` returns SETUP_REQUIRED before the handler runs
+ * when unconfigured, so `config.toolsLearning` is available for the default tool.
+ *
+ * Exposed as a `dirOverride`-closing factory mirroring `config.ts`.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md
+ * (`get_guidance`), spec.md US-2 / FR-021 / SC-011.
+ */
+import { loadBundledCatalog } from "../catalog/bundled/index.js";
+import { loadProfile } from "../profile/store.js";
+import { abilityKey, parseAbilityKey, } from "../schemas/common.js";
+import { GetGuidanceInputSchema, } from "../schemas/tools.js";
+import { defineTool } from "./types.js";
+import { computeStandings, rankByWeakness, standingFor, } from "./us2/standing.js";
+/** Resolve the default tool (explicit → first learning → claude-code). */
+const resolveTool = (requested, toolsLearning) => requested ?? toolsLearning[0] ?? "claude-code";
+/** Find the catalog topic whose `(class, id)` serializes to `key`. */
+const findTopicByKey = (topics, key) => topics.find((topic) => abilityKey(topic.class, topic.id) === key);
+/**
+ * Pick the authored item whose `guidance` best fits `currentTier`: prefer an
+ * item AT the current tier (or tier 100 when the learner has not graduated, so
+ * tier is 0), else the nearest item ABOVE it, else any item. Returns `undefined`
+ * only when the topic has no items at all.
+ */
+const guidanceItemFor = (topic, currentTier) => {
+    if (topic.items.length === 0)
+        return undefined;
+    const floor = currentTier === 0 ? 100 : currentTier;
+    const atTier = topic.items.find((item) => item.tier === floor);
+    if (atTier !== undefined)
+        return atTier;
+    const above = [...topic.items]
+        .filter((item) => item.tier >= floor)
+        .sort((a, b) => a.tier - b.tier)[0];
+    if (above !== undefined)
+        return above;
+    // Below the floor (learner graduated past authored content): take the highest.
+    return [...topic.items].sort((a, b) => b.tier - a.tier)[0];
+};
+/** Build the contract result for one resolved topic standing. */
+const guidanceResultFor = (standing) => {
+    const { topic, key, row } = standing;
+    const item = guidanceItemFor(topic, row.tier);
+    const guidance = item?.guidance ?? topic.summary;
+    const nextStep = topic.items.length > 0
+        ? {
+            action: "quiz",
+            detail: `Try a short quiz on "${topic.title}" to ${row.status === "not_started" ? "establish a baseline" : "reinforce and advance"}.`,
+        }
+        : {
+            action: "read",
+            detail: `Review "${topic.title}": ${topic.summary}`,
+        };
+    return { key, title: topic.title, currentTier: row.tier, guidance, nextStep };
+};
+/**
+ * Resolve the standing `get_guidance` should report on. With a `key`, guide on
+ * that exact topic (scoped via its own class). With no `key`, auto-select the
+ * weakest/stale in-scope topic for the resolved tool.
+ *
+ * @throws {Error} if a supplied `key` matches no catalog topic.
+ */
+const resolveStanding = (input, topics, profile) => {
+    if (input.key !== undefined) {
+        // Validate the key shape (throws on malformed) before lookup.
+        parseAbilityKey(input.key);
+        const topic = findTopicByKey(topics, input.key);
+        if (topic === undefined) {
+            throw new Error(`get_guidance: no catalog topic matches key ${JSON.stringify(input.key)}`);
+        }
+        return standingFor(topic, profile);
+    }
+    const tool = resolveTool(input.tool, profile.config?.toolsLearning ?? []);
+    const ranked = rankByWeakness(computeStandings(topics, profile, tool));
+    const weakest = ranked[0];
+    if (weakest === undefined) {
+        throw new Error(`get_guidance: no topics available for tool ${JSON.stringify(tool)}`);
+    }
+    return weakest;
+};
+/**
+ * Build the `get_guidance` tool module (US-2).
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @returns The erased registry entry for `get_guidance`.
+ */
+export const makeGetGuidanceTool = (dirOverride) => defineTool({
+    name: "get_guidance",
+    description: "Return teaching guidance and what to learn next for a topic or the weakest area. Read-only.",
+    inputSchema: GetGuidanceInputSchema,
+    handler: async (input) => {
+        const profile = await loadProfile(dirOverride);
+        const { topics } = loadBundledCatalog();
+        const standing = resolveStanding(input, topics, profile);
+        return guidanceResultFor(standing);
+    },
+});
+/** Default `get_guidance` module (env / `~/.vibe-hero`), used by the registry. */
+export const getGuidanceTool = makeGetGuidanceTool();
+//# sourceMappingURL=guidance.js.map

package/dist/tools/guidance.js.map

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

package/dist/tools/listTopics.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @file Real `list_topics` tool module (T026, US-2).
+ *
+ * Enumerates the catalog's topics, optionally filtered by `tool` and/or `class`,
+ * returning one row per topic (`{ key, id, class, title, tiers, itemCount }`)
+ * plus the catalog `version`. Works offline against the bundled snapshot
+ * (FR-025); `catalogVersion` comes from the manifest derived over the loaded
+ * topics (the placeholder `0.0.0-bundled` until the fetch layer supplies a real
+ * semver — see `buildManifest`).
+ *
+ * Telemetry-free (SC-011): enumeration reads only the catalog, never the
+ * profile's observation/offer state. Gated (FR-032) — `index.ts` returns
+ * SETUP_REQUIRED before the handler runs when unconfigured.
+ *
+ * Catalog source: resolves via {@link resolveCatalog} (fresh-fetch → cache →
+ * bundled, T054). With no `VIBE_HERO_CONTENT_URL` configured this is exactly the
+ * prior bundled behavior; when a source is configured the reported
+ * `catalogVersion` advances after a published update (SC-007). All remote
+ * failures degrade silently to cache/bundled (FR-027).
+ *
+ * Filters:
+ * - `class` ("general" | "tool") matches a topic's `class.kind`.
+ * - `tool` keeps `general` topics (they apply to every tool) plus tool-scoped
+ *   topics whose tool matches — the same scoping rule `get_status` uses.
+ *
+ * Exposed as a `(dirOverride, resolver)` factory: `dirOverride` flows to the
+ * content-cache dir (sibling of the profile home), and `resolver` is the catalog
+ * source seam (defaults to {@link resolveCatalog}) so tests can inject a fake
+ * fetch/cache without touching the network.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md (`list_topics`),
+ * spec.md US-2 / FR-025 / FR-026 / FR-027 / SC-006 / SC-007.
+ */
+import { type ResolvedCatalog } from "../catalog/resolve.js";
+import { type AnyToolModule } from "./types.js";
+/**
+ * Catalog-resolution seam for {@link makeListTopicsTool}. Mirrors
+ * {@link resolveCatalog}'s signature so tests can inject a fake fetch/cache while
+ * production uses the real fresh-fetch → cache → bundled resolution.
+ */
+export type CatalogResolver = (dirOverride?: string) => Promise<ResolvedCatalog>;
+/**
+ * Build the `list_topics` tool module (US-2).
+ *
+ * @param dirOverride - Profile-home override (test seam); flows to the content
+ *   cache dir used by {@link resolveCatalog}.
+ * @param resolver - Catalog-resolution seam (test seam); defaults to
+ *   {@link resolveCatalog} (fresh-fetch → cache → bundled). Tests inject a fake
+ *   resolver/fetch so no real network is hit.
+ * @returns The erased registry entry for `list_topics`.
+ */
+export declare const makeListTopicsTool: (dirOverride?: string, resolver?: CatalogResolver) => AnyToolModule;
+/** Default `list_topics` module (env / `~/.vibe-hero`), used by the registry. */
+export declare const listTopicsTool: AnyToolModule;
+//# sourceMappingURL=listTopics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"listTopics.d.ts","sourceRoot":"","sources":["../../src/tools/listTopics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAS7E,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAG5D;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,WAAW,CAAC,EAAE,MAAM,KACjB,OAAO,CAAC,eAAe,CAAC,CAAC;AAS9B;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC7B,cAAc,MAAM,EACpB,WAAU,eAAgC,KACzC,aA6BC,CAAC;AAEL,iFAAiF;AACjF,eAAO,MAAM,cAAc,EAAE,aAAoC,CAAC"}

package/dist/tools/listTopics.js

@@ -0,0 +1,78 @@
+/**
+ * @file Real `list_topics` tool module (T026, US-2).
+ *
+ * Enumerates the catalog's topics, optionally filtered by `tool` and/or `class`,
+ * returning one row per topic (`{ key, id, class, title, tiers, itemCount }`)
+ * plus the catalog `version`. Works offline against the bundled snapshot
+ * (FR-025); `catalogVersion` comes from the manifest derived over the loaded
+ * topics (the placeholder `0.0.0-bundled` until the fetch layer supplies a real
+ * semver — see `buildManifest`).
+ *
+ * Telemetry-free (SC-011): enumeration reads only the catalog, never the
+ * profile's observation/offer state. Gated (FR-032) — `index.ts` returns
+ * SETUP_REQUIRED before the handler runs when unconfigured.
+ *
+ * Catalog source: resolves via {@link resolveCatalog} (fresh-fetch → cache →
+ * bundled, T054). With no `VIBE_HERO_CONTENT_URL` configured this is exactly the
+ * prior bundled behavior; when a source is configured the reported
+ * `catalogVersion` advances after a published update (SC-007). All remote
+ * failures degrade silently to cache/bundled (FR-027).
+ *
+ * Filters:
+ * - `class` ("general" | "tool") matches a topic's `class.kind`.
+ * - `tool` keeps `general` topics (they apply to every tool) plus tool-scoped
+ *   topics whose tool matches — the same scoping rule `get_status` uses.
+ *
+ * Exposed as a `(dirOverride, resolver)` factory: `dirOverride` flows to the
+ * content-cache dir (sibling of the profile home), and `resolver` is the catalog
+ * source seam (defaults to {@link resolveCatalog}) so tests can inject a fake
+ * fetch/cache without touching the network.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md (`list_topics`),
+ * spec.md US-2 / FR-025 / FR-026 / FR-027 / SC-006 / SC-007.
+ */
+import { resolveCatalog } from "../catalog/resolve.js";
+import { abilityKey } from "../schemas/common.js";
+import { ListTopicsInputSchema, } from "../schemas/tools.js";
+import { defineTool } from "./types.js";
+import { topicInScope } from "./us2/standing.js";
+/** The narrowed `class` discriminator surfaced in a {@link ListTopicsRow}. */
+const classKind = (topic) => topic.class.kind;
+/** Distinct tiers present in a topic's items, ascending (manifest convention). */
+const topicTiers = (topic) => [...new Set(topic.items.map((item) => item.tier))].sort((a, b) => a - b);
+/**
+ * Build the `list_topics` tool module (US-2).
+ *
+ * @param dirOverride - Profile-home override (test seam); flows to the content
+ *   cache dir used by {@link resolveCatalog}.
+ * @param resolver - Catalog-resolution seam (test seam); defaults to
+ *   {@link resolveCatalog} (fresh-fetch → cache → bundled). Tests inject a fake
+ *   resolver/fetch so no real network is hit.
+ * @returns The erased registry entry for `list_topics`.
+ */
+export const makeListTopicsTool = (dirOverride, resolver = resolveCatalog) => defineTool({
+    name: "list_topics",
+    description: "Enumerate catalog topics, optionally filtered by tool or class. Read-only.",
+    inputSchema: ListTopicsInputSchema,
+    handler: async (input) => {
+        // Resolve via fresh-fetch → cache → bundled (T054). `catalogVersion` is
+        // the winning source's version, independent of the caller's filter, so it
+        // stays stable across queries and advances after a published update.
+        const { topics, catalogVersion } = await resolver(dirOverride);
+        const filtered = topics
+            .filter((topic) => topicInScope(topic, input.tool))
+            .filter((topic) => input.class === undefined || classKind(topic) === input.class);
+        const rows = filtered.map((topic) => ({
+            key: abilityKey(topic.class, topic.id),
+            id: topic.id,
+            class: classKind(topic),
+            title: topic.title,
+            tiers: topicTiers(topic),
+            itemCount: topic.items.length,
+        }));
+        return { topics: rows, catalogVersion };
+    },
+});
+/** Default `list_topics` module (env / `~/.vibe-hero`), used by the registry. */
+export const listTopicsTool = makeListTopicsTool();
+//# sourceMappingURL=listTopics.js.map

package/dist/tools/listTopics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listTopics.js","sourceRoot":"","sources":["../../src/tools/listTopics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,cAAc,EAAwB,MAAM,uBAAuB,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,EACL,qBAAqB,GAItB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAsB,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAWjD,8EAA8E;AAC9E,MAAM,SAAS,GAAG,CAAC,KAAY,EAAsB,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;AAEzE,kFAAkF;AAClF,MAAM,UAAU,GAAG,CAAC,KAAY,EAA0B,EAAE,CAC1D,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,WAAoB,EACpB,WAA4B,cAAc,EAC3B,EAAE,CACjB,UAAU,CAAC;IACT,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,4EAA4E;IAC9E,WAAW,EAAE,qBAAqB;IAClC,OAAO,EAAE,KAAK,EAAE,KAAsB,EAA6B,EAAE;QACnE,wEAAwE;QACxE,0EAA0E;QAC1E,qEAAqE;QACrE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,CAAC;QAE/D,MAAM,QAAQ,GAAG,MAAM;aACpB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;aAClD,MAAM,CACL,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,KAAK,CACzE,CAAC;QAEJ,MAAM,IAAI,GAAoB,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACrD,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;YACtC,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC;YACvB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC;YACxB,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;SAC9B,CAAC,CAAC,CAAC;QAEJ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IAC1C,CAAC;CACF,CAAC,CAAC;AAEL,iFAAiF;AACjF,MAAM,CAAC,MAAM,cAAc,GAAkB,kBAAkB,EAAE,CAAC"}

package/dist/tools/offers.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @file Real `get_offer` / `record_offer_response` tool modules (T036, US-1).
+ *
+ * These two tools are the end-of-work offer surface, thin wrappers over the pure
+ * offer engine (`../observation/offers.js`):
+ *
+ *  - `get_offer` ({sessionId, tool}) resolves whether an offer may surface at an
+ *    end-of-work breakpoint and for which key, honoring cadence + anti-fatigue
+ *    via {@link resolveOffer}. The candidate pool is the per-session
+ *    `OfferLedger.candidateKeys` accumulated by `record_observation` (get_offer
+ *    receives no signals of its own). When an offer surfaces it is recorded via
+ *    {@link markOffered} so the cadence caps apply on the next call, and the
+ *    offer's `prompt` is built from the catalog topic's summary.
+ *
+ *  - `record_offer_response` ({sessionId, key, response}) persists the
+ *    accept/decline/defer outcome: a decline applies within-session suppression
+ *    (FR-020) AND cross-session backoff + eventual global mute (FR-020b) via
+ *    {@link applyDecline}; an accept resets the consecutive-decline counter and
+ *    clears the mute via {@link applyAccept}; a defer leaves state unchanged.
+ *
+ * Both delegate the decision/state math to the pure engine and own only the IO:
+ * clock, catalog load, and the atomic {@link updateProfile} write. Neither tool
+ * EVER touches abilities/graduations/quizHistory — offers never score (FR-005,
+ * SC-003).
+ *
+ * Gated (FR-032): NOT exempt — `index.ts`/`withSetupGate` returns SETUP_REQUIRED
+ * when `profile.config` is absent. The handlers assume a configured profile.
+ *
+ * Each tool is a `(dirOverride, catalogLoader)` factory mirroring
+ * `startQuiz.ts`/`recordObservation.ts`.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md (`get_offer`,
+ * `record_offer_response`), spec.md FR-019/020/020a/020b, data-model.md
+ * (§ OfferLedger), src/config.ts (ASSESSMENT_CONFIG).
+ */
+import type { CatalogLoadResult } from "../catalog/loader.js";
+import { type AnyToolModule } from "./types.js";
+/** Catalog source override (test seam); defaults to the bundled snapshot. */
+export type CatalogLoader = () => CatalogLoadResult;
+/**
+ * Build the `get_offer` tool module (US-1).
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @param catalogLoader - Catalog source override (test seam); defaults to the
+ *   bundled snapshot {@link loadBundledCatalog}.
+ * @returns The erased registry entry for `get_offer`.
+ */
+export declare const makeGetOfferTool: (dirOverride?: string, catalogLoader?: CatalogLoader) => AnyToolModule;
+/**
+ * Build the `record_offer_response` tool module (US-1).
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @returns The erased registry entry for `record_offer_response`.
+ */
+export declare const makeRecordOfferResponseTool: (dirOverride?: string) => AnyToolModule;
+/** Default `get_offer` module (env / `~/.vibe-hero` + bundled catalog). */
+export declare const getOfferTool: AnyToolModule;
+/** Default `record_offer_response` module (env / `~/.vibe-hero`). */
+export declare const recordOfferResponseTool: AnyToolModule;
+//# sourceMappingURL=offers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"offers.d.ts","sourceRoot":"","sources":["../../src/tools/offers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAqB9D,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5D,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,MAAM,iBAAiB,CAAC;AAapD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAC3B,cAAc,MAAM,EACpB,gBAAe,aAAkC,KAChD,aA0DC,CAAC;AAiBL;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GACtC,cAAc,MAAM,KACnB,aA8CC,CAAC;AAEL,2EAA2E;AAC3E,eAAO,MAAM,YAAY,EAAE,aAAkC,CAAC;AAE9D,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,EAAE,aACP,CAAC"}

package/dist/tools/offers.js

@@ -0,0 +1,152 @@
+/**
+ * @file Real `get_offer` / `record_offer_response` tool modules (T036, US-1).
+ *
+ * These two tools are the end-of-work offer surface, thin wrappers over the pure
+ * offer engine (`../observation/offers.js`):
+ *
+ *  - `get_offer` ({sessionId, tool}) resolves whether an offer may surface at an
+ *    end-of-work breakpoint and for which key, honoring cadence + anti-fatigue
+ *    via {@link resolveOffer}. The candidate pool is the per-session
+ *    `OfferLedger.candidateKeys` accumulated by `record_observation` (get_offer
+ *    receives no signals of its own). When an offer surfaces it is recorded via
+ *    {@link markOffered} so the cadence caps apply on the next call, and the
+ *    offer's `prompt` is built from the catalog topic's summary.
+ *
+ *  - `record_offer_response` ({sessionId, key, response}) persists the
+ *    accept/decline/defer outcome: a decline applies within-session suppression
+ *    (FR-020) AND cross-session backoff + eventual global mute (FR-020b) via
+ *    {@link applyDecline}; an accept resets the consecutive-decline counter and
+ *    clears the mute via {@link applyAccept}; a defer leaves state unchanged.
+ *
+ * Both delegate the decision/state math to the pure engine and own only the IO:
+ * clock, catalog load, and the atomic {@link updateProfile} write. Neither tool
+ * EVER touches abilities/graduations/quizHistory — offers never score (FR-005,
+ * SC-003).
+ *
+ * Gated (FR-032): NOT exempt — `index.ts`/`withSetupGate` returns SETUP_REQUIRED
+ * when `profile.config` is absent. The handlers assume a configured profile.
+ *
+ * Each tool is a `(dirOverride, catalogLoader)` factory mirroring
+ * `startQuiz.ts`/`recordObservation.ts`.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md (`get_offer`,
+ * `record_offer_response`), spec.md FR-019/020/020a/020b, data-model.md
+ * (§ OfferLedger), src/config.ts (ASSESSMENT_CONFIG).
+ */
+import { ASSESSMENT_CONFIG } from "../config.js";
+import { loadBundledCatalog } from "../catalog/bundled/index.js";
+import { loadProfile, updateProfile } from "../profile/store.js";
+import { abilityKey } from "../schemas/common.js";
+import { GetOfferInputSchema, RecordOfferResponseInputSchema, } from "../schemas/tools.js";
+import { applyAccept, applyDecline, applyDefer, ledgerForSession, markOffered, resolveOffer, } from "../observation/offers.js";
+import { defineTool } from "./types.js";
+/** Find the catalog topic whose `(class, id)` serializes to `key`. */
+const findTopicByKey = (topics, key) => topics.find((topic) => abilityKey(topic.class, topic.id) === key);
+/** Build the user-facing offer prompt for a topic (privacy-safe, no scoring). */
+const offerPrompt = (topic) => `You just exercised "${topic.title}". Want a quick quiz to check your grasp? (${topic.summary})`;
+/**
+ * Build the `get_offer` tool module (US-1).
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @param catalogLoader - Catalog source override (test seam); defaults to the
+ *   bundled snapshot {@link loadBundledCatalog}.
+ * @returns The erased registry entry for `get_offer`.
+ */
+export const makeGetOfferTool = (dirOverride, catalogLoader = loadBundledCatalog) => defineTool({
+    name: "get_offer",
+    description: "Resolve whether to surface an end-of-work learning offer for the session.",
+    inputSchema: GetOfferInputSchema,
+    handler: async (input) => {
+        const now = new Date();
+        const profile = await loadProfile(dirOverride);
+        const config = profile.config;
+        // Gated: config is present. Reconcile the ledger to THIS session (a new
+        // session id rolls over the per-session accounting) before deciding.
+        const ledger = ledgerForSession(profile.offers, input.sessionId);
+        const decision = resolveOffer({
+            proactiveOffers: config?.proactiveOffers ?? false,
+            offerCadence: config?.offerCadence ?? "off",
+            ledger,
+            backoff: profile.backoff,
+            candidates: ledger.candidateKeys,
+        }, now);
+        if (decision.kind === "suppressed") {
+            // Persist any session rollover (so a fresh session id is recorded) but
+            // never touch scoring state.
+            if (ledger.sessionId !== profile.offers.sessionId) {
+                await persistLedger(ledger, dirOverride);
+            }
+            return { suppressed: decision.reason };
+        }
+        const { topics } = catalogLoader();
+        const topic = findTopicByKey(topics, decision.key);
+        if (topic === undefined) {
+            // The candidate key has no resolvable topic (catalog drift): treat as
+            // no candidate rather than throwing — offers must never crash the path.
+            if (ledger.sessionId !== profile.offers.sessionId) {
+                await persistLedger(ledger, dirOverride);
+            }
+            return { suppressed: "no_candidate" };
+        }
+        // Record that the offer surfaced so the cadence caps apply next time.
+        const offered = markOffered(ledger, decision.key);
+        await persistLedger(offered, dirOverride);
+        return {
+            offer: {
+                key: decision.key,
+                title: topic.title,
+                prompt: offerPrompt(topic),
+            },
+        };
+    },
+});
+/**
+ * Persist ONLY the `offers` ledger block (atomic). Never touches abilities,
+ * graduations, quizHistory, reviewSchedule, or backoff — keeping the offer path
+ * score-free (FR-005 / SC-003).
+ */
+const persistLedger = async (ledger, dirOverride) => {
+    await updateProfile((current) => ({ ...current, offers: ledger }), dirOverride);
+};
+/**
+ * Build the `record_offer_response` tool module (US-1).
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @returns The erased registry entry for `record_offer_response`.
+ */
+export const makeRecordOfferResponseTool = (dirOverride) => defineTool({
+    name: "record_offer_response",
+    description: "Record an accept/decline/defer offer response so cadence and anti-nag are honored.",
+    inputSchema: RecordOfferResponseInputSchema,
+    handler: async (input) => {
+        const now = new Date();
+        // Single atomic read-modify-write so concurrent sessions serialize. Only
+        // the `offers` ledger + `backoff` change — scoring state is untouched.
+        await updateProfile((current) => {
+            const ledger = ledgerForSession(current.offers, input.sessionId);
+            switch (input.response) {
+                case "decline": {
+                    const { ledger: nextLedger, backoff } = applyDecline(ledger, current.backoff, input.key, now, ASSESSMENT_CONFIG);
+                    return { ...current, offers: nextLedger, backoff };
+                }
+                case "accept": {
+                    return {
+                        ...current,
+                        offers: ledger,
+                        backoff: applyAccept(current.backoff),
+                    };
+                }
+                case "defer": {
+                    const { ledger: nextLedger, backoff } = applyDefer(ledger, current.backoff);
+                    return { ...current, offers: nextLedger, backoff };
+                }
+            }
+        }, dirOverride);
+        return { ok: true };
+    },
+});
+/** Default `get_offer` module (env / `~/.vibe-hero` + bundled catalog). */
+export const getOfferTool = makeGetOfferTool();
+/** Default `record_offer_response` module (env / `~/.vibe-hero`). */
+export const recordOfferResponseTool = makeRecordOfferResponseTool();
+//# sourceMappingURL=offers.js.map

package/dist/tools/offers.js.map

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

package/dist/tools/placeholders.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file Tool registry (T020).
+ *
+ * This wires all 10 MCP tools into a single {@link TOOL_REGISTRY} that
+ * `index.ts` iterates over to register them. Each module carries its real input
+ * schema (from `schemas/tools.ts`) so the host-facing tool signatures are
+ * correct. `save_config` / `get_config` are the real US-0 implementations
+ * (`./config.js`, T022); `get_status` / `list_topics` / `get_guidance` are the
+ * real US-2 read tools (`./status.js`, `./listTopics.js`, `./guidance.js`,
+ * T025–T027); `start_quiz` / `submit_answer` are the real US-1 core-loop tools
+ * (`./startQuiz.js`, `./submitAnswer.js`, T031/T032); `record_observation` /
+ * `get_offer` / `record_offer_response` are the real US-1 offer tools
+ * (`./recordObservation.js`, `./offers.js`, T034/T036). All 10 are now real —
+ * no placeholders remain.
+ *
+ * The registration architecture and gate wiring delivered here stay unchanged.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md.
+ */
+import { type AnyToolModule } from "./types.js";
+/**
+ * All 10 vibe-hero MCP tools, in contract order. `index.ts` registers each one
+ * (wrapping the handler with the setup gate). This list is the single source of
+ * which tools exist.
+ */
+export declare const TOOL_REGISTRY: readonly AnyToolModule[];
+//# sourceMappingURL=placeholders.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"placeholders.d.ts","sourceRoot":"","sources":["../../src/tools/placeholders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAUhD;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,aAAa,EAejD,CAAC"}

package/dist/tools/placeholders.js

@@ -0,0 +1,49 @@
+/**
+ * @file Tool registry (T020).
+ *
+ * This wires all 10 MCP tools into a single {@link TOOL_REGISTRY} that
+ * `index.ts` iterates over to register them. Each module carries its real input
+ * schema (from `schemas/tools.ts`) so the host-facing tool signatures are
+ * correct. `save_config` / `get_config` are the real US-0 implementations
+ * (`./config.js`, T022); `get_status` / `list_topics` / `get_guidance` are the
+ * real US-2 read tools (`./status.js`, `./listTopics.js`, `./guidance.js`,
+ * T025–T027); `start_quiz` / `submit_answer` are the real US-1 core-loop tools
+ * (`./startQuiz.js`, `./submitAnswer.js`, T031/T032); `record_observation` /
+ * `get_offer` / `record_offer_response` are the real US-1 offer tools
+ * (`./recordObservation.js`, `./offers.js`, T034/T036). All 10 are now real —
+ * no placeholders remain.
+ *
+ * The registration architecture and gate wiring delivered here stay unchanged.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md.
+ */
+import { saveConfigTool, getConfigTool } from "./config.js";
+import { getStatusTool } from "./status.js";
+import { listTopicsTool } from "./listTopics.js";
+import { getGuidanceTool } from "./guidance.js";
+import { startQuizTool } from "./startQuiz.js";
+import { submitAnswerTool } from "./submitAnswer.js";
+import { recordObservationTool } from "./recordObservation.js";
+import { getOfferTool, recordOfferResponseTool } from "./offers.js";
+/**
+ * All 10 vibe-hero MCP tools, in contract order. `index.ts` registers each one
+ * (wrapping the handler with the setup gate). This list is the single source of
+ * which tools exist.
+ */
+export const TOOL_REGISTRY = [
+    // Real US-2 read tools (T025–T027).
+    getStatusTool,
+    listTopicsTool,
+    getGuidanceTool,
+    // Real US-1 core-loop tools (T031/T032).
+    startQuizTool,
+    submitAnswerTool,
+    // Real US-0 implementations (T022).
+    saveConfigTool,
+    getConfigTool,
+    // Real US-1 observation/offer tools (T034/T036).
+    recordObservationTool,
+    getOfferTool,
+    recordOfferResponseTool,
+];
+//# sourceMappingURL=placeholders.js.map

package/dist/tools/placeholders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholders.js","sourceRoot":"","sources":["../../src/tools/placeholders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAEpE;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAA6B;IACrD,oCAAoC;IACpC,aAAa;IACb,cAAc;IACd,eAAe;IACf,yCAAyC;IACzC,aAAa;IACb,gBAAgB;IAChB,oCAAoC;IACpC,cAAc;IACd,aAAa;IACb,iDAAiD;IACjD,qBAAqB;IACrB,YAAY;IACZ,uBAAuB;CACxB,CAAC"}

package/dist/tools/recordObservation.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file Real `record_observation` tool module (T034, US-1).
+ *
+ * Intake for the observation source (the real-time Claude Code hook in v1). It
+ * accepts derived, privacy-safe signals (`toolName` / `mcpTool` / `success` /
+ * `toolUseId`) plus a `sessionId`, matches them to candidate topic keys against
+ * the catalog's {@link TriggerSignal}s, accumulates the candidates into the
+ * per-session {@link OfferLedger}, and returns `{ offerCandidates }`.
+ *
+ * Trigger-only — AWARDS NOTHING (FR-005 / SC-003). It deliberately touches ONLY
+ * the profile's `offers` ledger (its `sessionId` / candidate accounting). It
+ * never reads or writes `abilities`, `graduations`, `quizHistory`, or
+ * `reviewSchedule`, so observed usage with no answered quiz produces exactly 0
+ * change to points or graduation state (SC-003) — the integration test asserts
+ * those fields are byte-identical before/after.
+ *
+ * v1 scope note: a SINGLE real-time hook source feeds this tool. FR-017's
+ * two-source (hook + transcript backfill) correlation by `tool_use_id` is
+ * architecture-ready (signals carry `toolUseId`; the {@link ObservationSource}
+ * seam exists) but is NOT built here, per tasks.md.
+ *
+ * Gated (FR-032): NOT exempt — `index.ts`/`withSetupGate` returns SETUP_REQUIRED
+ * before this handler runs when `profile.config` is absent. The handler assumes
+ * a configured profile and reads `config.proactiveOffers` / `config.offerCadence`
+ * only to short-circuit candidate work when offers are disabled (so a disabled
+ * user never accrues candidate state needlessly).
+ *
+ * Exposed as a `(dirOverride, catalogLoader)` factory mirroring
+ * `startQuiz.ts` / `status.ts`: the registry uses the default instance
+ * (env / `~/.vibe-hero` + bundled catalog); tests inject a temp home + fixture
+ * catalog.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md
+ * (`record_observation`), spec.md FR-005 / FR-015..017 / FR-018 / SC-003,
+ * data-model.md (§ OfferLedger).
+ */
+import type { CatalogLoadResult } from "../catalog/loader.js";
+import { type AnyToolModule } from "./types.js";
+/** Catalog source override (test seam); defaults to the bundled snapshot. */
+export type CatalogLoader = () => CatalogLoadResult;
+/**
+ * Build the `record_observation` tool module (US-1).
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @param catalogLoader - Catalog source override (test seam); defaults to the
+ *   bundled snapshot {@link loadBundledCatalog}.
+ * @returns The erased registry entry for `record_observation`.
+ */
+export declare const makeRecordObservationTool: (dirOverride?: string, catalogLoader?: CatalogLoader) => AnyToolModule;
+/** Default `record_observation` module (env / `~/.vibe-hero` + bundled catalog). */
+export declare const recordObservationTool: AnyToolModule;
+//# sourceMappingURL=recordObservation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recordObservation.d.ts","sourceRoot":"","sources":["../../src/tools/recordObservation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAe9D,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5D,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,GACpC,cAAc,MAAM,EACpB,gBAAe,aAAkC,KAChD,aAuDC,CAAC;AAEL,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,EAAE,aAA2C,CAAC"}