@vibe-hero/server 0.1.0

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

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

package/dist/schemas/tools.js

@@ -0,0 +1,286 @@
+/**
+ * @file MCP tool input/output schemas.
+ *
+ * One input + output schema per MCP tool. All inputs/outputs are Zod-validated
+ * both directions. Every tool (except get_config/save_config) may instead
+ * return the {@link SetupRequiredSchema} gate sentinel when `profile.config` is
+ * absent (FR-032).
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md.
+ */
+import { z } from "zod";
+import { AbilityKeySchema, TierSchema, ToolIdSchema, QuestionTypeSchema, GradeSchema, } from "./common.js";
+import { ChoiceSchema, RubricCriterionSchema } from "./content.js";
+import { ConfigSchema } from "./profile.js";
+/**
+ * The setup gate sentinel. Returned by any gated tool when `profile.config` is
+ * absent (FR-032). Tool result schemas that can be gated are unioned with this.
+ */
+export const SetupRequiredSchema = z.object({
+    status: z.literal("SETUP_REQUIRED"),
+    message: z.string().min(1),
+    setupSkill: z.string().min(1),
+});
+/**
+ * Wrap a tool result schema so it can also be the gate sentinel. Discriminated
+ * on `status` is not possible for arbitrary object results, so this is a plain
+ * union; callers narrow on the `status === "SETUP_REQUIRED"` field.
+ */
+const gated = (result) => z.union([SetupRequiredSchema, result]);
+// ---------------------------------------------------------------------------
+// get_status
+// ---------------------------------------------------------------------------
+/** Input for `get_status`. */
+export const GetStatusInputSchema = z.object({
+    tool: ToolIdSchema.optional(),
+});
+/** Per-topic standing row in `get_status`. */
+export const StatusTopicSchema = z.object({
+    key: AbilityKeySchema,
+    title: z.string(),
+    tier: z.union([TierSchema, z.literal(0)]),
+    status: z.enum(["current", "due_for_review", "not_started"]),
+    ability: z.number(),
+});
+/** Result for `get_status`. */
+export const GetStatusResultSchema = z.object({
+    tool: ToolIdSchema,
+    topics: z.array(StatusTopicSchema),
+    dueForReview: z.array(z.string()),
+    suggestions: z.array(z.object({ key: AbilityKeySchema, reason: z.string() })),
+});
+/** Output for `get_status` (may be gated). */
+export const GetStatusOutputSchema = gated(GetStatusResultSchema);
+// ---------------------------------------------------------------------------
+// list_topics
+// ---------------------------------------------------------------------------
+/** Input for `list_topics`. */
+export const ListTopicsInputSchema = z.object({
+    tool: ToolIdSchema.optional(),
+    class: z.enum(["general", "tool"]).optional(),
+});
+/** One topic row in `list_topics`. */
+export const ListTopicsRowSchema = z.object({
+    key: AbilityKeySchema,
+    id: z.string(),
+    class: z.enum(["general", "tool"]),
+    title: z.string(),
+    tiers: z.array(TierSchema),
+    itemCount: z.number().int().nonnegative(),
+});
+/** Result for `list_topics`. */
+export const ListTopicsResultSchema = z.object({
+    topics: z.array(ListTopicsRowSchema),
+    catalogVersion: z.string(),
+});
+/** Output for `list_topics` (may be gated). */
+export const ListTopicsOutputSchema = gated(ListTopicsResultSchema);
+// ---------------------------------------------------------------------------
+// get_guidance
+// ---------------------------------------------------------------------------
+/** Input for `get_guidance`. No `key` ⇒ pick weakest/stale for `tool`. */
+export const GetGuidanceInputSchema = z.object({
+    key: AbilityKeySchema.optional(),
+    tool: ToolIdSchema.optional(),
+});
+/** Result for `get_guidance`. */
+export const GetGuidanceResultSchema = z.object({
+    key: AbilityKeySchema,
+    title: z.string(),
+    currentTier: z.union([TierSchema, z.literal(0)]),
+    guidance: z.string(),
+    nextStep: z.object({
+        action: z.enum(["quiz", "read"]),
+        detail: z.string(),
+    }),
+});
+/** Output for `get_guidance` (may be gated). */
+export const GetGuidanceOutputSchema = gated(GetGuidanceResultSchema);
+// ---------------------------------------------------------------------------
+// start_quiz
+// ---------------------------------------------------------------------------
+/**
+ * Input for `start_quiz`.
+ *
+ * `allowFreeForm` is the graceful-degradation switch (FR-014, T049): when the
+ * host agent cannot judge a free-form answer (no judging capability), the caller
+ * passes `false` and the selection EXCLUDES `free_form` items, preferring
+ * deterministic ones so the quiz still completes rather than serving an
+ * unjudgeable item. It defaults to `true` (free-form judging is available).
+ */
+export const StartQuizInputSchema = z.object({
+    key: AbilityKeySchema,
+    length: z.union([z.literal(3), z.literal(4), z.literal(5)]).optional(),
+    allowFreeForm: z.boolean().optional(),
+});
+/**
+ * An item as presented to the host agent. Deterministic items omit answer keys
+ * and rubric/referenceAnswer; `free_form` items include `rubric.criteria` (with
+ * ids) AND `referenceAnswer` so the host agent can judge.
+ */
+export const PresentedItemSchema = z.object({
+    itemId: z.string(),
+    tier: TierSchema,
+    type: QuestionTypeSchema,
+    prompt: z.string(),
+    choices: z.array(ChoiceSchema).optional(),
+    rubric: z.object({ criteria: z.array(RubricCriterionSchema) }).optional(),
+    referenceAnswer: z.string().optional(),
+});
+/** Result for `start_quiz`. */
+export const StartQuizResultSchema = z.object({
+    quizId: z.string(),
+    items: z.array(PresentedItemSchema),
+});
+/** Output for `start_quiz` (may be gated). */
+export const StartQuizOutputSchema = gated(StartQuizResultSchema);
+// ---------------------------------------------------------------------------
+// submit_answer
+// ---------------------------------------------------------------------------
+/** Deterministic answer payload (multiple_choice / short_answer). */
+export const SubmitAnswerDeterministicInputSchema = z.object({
+    quizId: z.string(),
+    itemId: z.string(),
+    answer: z.object({
+        choiceId: z.string().optional(),
+        text: z.string().optional(),
+    }),
+});
+/**
+ * Free-form per-criterion verdict from the host agent. A single-boolean verdict
+ * is rejected as non-conformant (anti-gaming, critique E2): each criterion id
+ * must carry its own `met` + `justification`. The MCP computes the score.
+ */
+export const FreeFormVerdictSchema = z.object({
+    criteria: z
+        .array(z.object({
+        id: z.string().min(1),
+        met: z.boolean(),
+        justification: z.string().min(1),
+    }))
+        .min(1),
+});
+/** Free-form answer payload (host-agent verdict). */
+export const SubmitAnswerFreeFormInputSchema = z.object({
+    quizId: z.string(),
+    itemId: z.string(),
+    verdict: FreeFormVerdictSchema,
+});
+/**
+ * Input for `submit_answer`: either a deterministic answer or a free-form
+ * verdict. Discriminated structurally (presence of `answer` vs. `verdict`).
+ */
+export const SubmitAnswerInputSchema = z.union([
+    SubmitAnswerDeterministicInputSchema,
+    SubmitAnswerFreeFormInputSchema,
+]);
+/** Result for `submit_answer`. */
+export const SubmitAnswerResultSchema = z.object({
+    grade: GradeSchema,
+    score: z.number().min(0).max(1),
+    correctAnswer: z.string().optional(),
+    guidance: z.string(),
+    ability: z.object({ before: z.number(), after: z.number() }),
+    graduation: z
+        .object({
+        changed: z.boolean(),
+        tier: TierSchema.optional(),
+        status: z.string().optional(),
+        reason: z.string().optional(),
+    })
+        .optional(),
+});
+/** Output for `submit_answer` (may be gated). */
+export const SubmitAnswerOutputSchema = gated(SubmitAnswerResultSchema);
+// ---------------------------------------------------------------------------
+// save_config (not gated — clears the gate)
+// ---------------------------------------------------------------------------
+/** Input for `save_config`. */
+export const SaveConfigInputSchema = z.object({
+    toolsLearning: z.array(ToolIdSchema),
+    offerCadence: z.enum(["off", "per_session", "per_topic"]),
+    proactiveOffers: z.boolean(),
+    quizLength: z.union([z.literal(3), z.literal(4), z.literal(5)]).optional(),
+});
+/** Result/output for `save_config` (never gated). */
+export const SaveConfigResultSchema = z.object({
+    ok: z.literal(true),
+    config: ConfigSchema,
+});
+export const SaveConfigOutputSchema = SaveConfigResultSchema;
+// ---------------------------------------------------------------------------
+// get_config (not gated — reports gate state)
+// ---------------------------------------------------------------------------
+/** Input for `get_config`. */
+export const GetConfigInputSchema = z.object({});
+/** Result/output for `get_config` (never gated). */
+export const GetConfigResultSchema = z.object({
+    configured: z.boolean(),
+    config: ConfigSchema.optional(),
+});
+export const GetConfigOutputSchema = GetConfigResultSchema;
+// ---------------------------------------------------------------------------
+// record_observation (trigger-only; never scores)
+// ---------------------------------------------------------------------------
+/** Input for `record_observation`. */
+export const RecordObservationInputSchema = z.object({
+    tool: ToolIdSchema,
+    signals: z.array(z.object({
+        toolName: z.string().optional(),
+        mcpTool: z.string().optional(),
+        success: z.boolean().optional(),
+        toolUseId: z.string().optional(),
+    })),
+    sessionId: z.string(),
+});
+/** One offer candidate from `record_observation`. */
+export const OfferCandidateSchema = z.object({
+    key: AbilityKeySchema,
+    title: z.string(),
+    reason: z.string(),
+});
+/** Result for `record_observation`. */
+export const RecordObservationResultSchema = z.object({
+    offerCandidates: z.array(OfferCandidateSchema),
+});
+/** Output for `record_observation` (may be gated). */
+export const RecordObservationOutputSchema = gated(RecordObservationResultSchema);
+// ---------------------------------------------------------------------------
+// get_offer
+// ---------------------------------------------------------------------------
+/** Input for `get_offer`. */
+export const GetOfferInputSchema = z.object({
+    sessionId: z.string(),
+    tool: ToolIdSchema,
+});
+/** Result for `get_offer`. */
+export const GetOfferResultSchema = z.object({
+    offer: z
+        .object({
+        key: AbilityKeySchema,
+        title: z.string(),
+        prompt: z.string(),
+    })
+        .optional(),
+    suppressed: z
+        .enum(["cadence", "declined", "offers_off", "no_candidate"])
+        .optional(),
+});
+/** Output for `get_offer` (may be gated). */
+export const GetOfferOutputSchema = gated(GetOfferResultSchema);
+// ---------------------------------------------------------------------------
+// record_offer_response
+// ---------------------------------------------------------------------------
+/** Input for `record_offer_response`. */
+export const RecordOfferResponseInputSchema = z.object({
+    sessionId: z.string(),
+    key: AbilityKeySchema,
+    response: z.enum(["accept", "decline", "defer"]),
+});
+/** Result for `record_offer_response`. */
+export const RecordOfferResponseResultSchema = z.object({
+    ok: z.literal(true),
+});
+/** Output for `record_offer_response` (may be gated). */
+export const RecordOfferResponseOutputSchema = gated(RecordOfferResponseResultSchema);
+//# sourceMappingURL=tools.js.map

package/dist/schemas/tools.js.map

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

package/dist/tools/config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @file Real `save_config` / `get_config` tool modules (T022, US-0).
+ *
+ * These two tools own the first-run setup gate's lifecycle: `save_config` writes
+ * the `config` block that clears the gate (FR-031/032) and `get_config` reports
+ * gate state. Both are exempt from {@link withSetupGate} (see
+ * {@link EXEMPT_TOOLS}) — gating them would deadlock setup.
+ *
+ * Clock note: the engine stays pure, but these tools live in the IO/tool layer,
+ * so they MAY read the wall clock to stamp `createdAt`/`updatedAt`
+ * (`new Date().toISOString()`). The store's atomic read-modify-write
+ * ({@link updateProfile}) is reused so a re-config never races a concurrent
+ * writer, and only the `config` field is replaced — abilities, graduations,
+ * review schedule, quiz history, and offer state are preserved (FR-033).
+ *
+ * Each tool is exposed as a factory closing over an optional `dirOverride`
+ * (the store's test seam): the registry uses the default instances (env /
+ * `~/.vibe-hero`), and tests build dir-scoped instances against a temp home.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md
+ * (`save_config` / `get_config`), spec.md FR-031 / FR-032 / FR-033.
+ */
+import { type AnyToolModule } from "./types.js";
+/**
+ * Build the `save_config` tool module (US-0, FR-031/033).
+ *
+ * Validates input, then atomically replaces only the profile's `config` block
+ * via {@link updateProfile}. Because every other field is spread through
+ * untouched, re-running setup updates preferences without losing learning
+ * progress (FR-033). Returns `{ ok: true, config }` with the persisted config.
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @returns The erased registry entry for `save_config`.
+ */
+export declare const makeSaveConfigTool: (dirOverride?: string) => AnyToolModule;
+/**
+ * Build the `get_config` tool module (US-0).
+ *
+ * Reads the profile (never throws — a missing/corrupt profile degrades to an
+ * unconfigured one) and reports whether `config` is present, echoing it when so.
+ * Skills/hooks use this to know the gate state without triggering it.
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @returns The erased registry entry for `get_config`.
+ */
+export declare const makeGetConfigTool: (dirOverride?: string) => AnyToolModule;
+/** Default `save_config` module (env / `~/.vibe-hero`), used by the registry. */
+export declare const saveConfigTool: AnyToolModule;
+/** Default `get_config` module (env / `~/.vibe-hero`), used by the registry. */
+export declare const getConfigTool: AnyToolModule;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/tools/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAWH,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AA+B5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,cAAc,MAAM,KAAG,aAsBtD,CAAC;AAEL;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,cAAc,MAAM,KAAG,aAYrD,CAAC;AAEL,iFAAiF;AACjF,eAAO,MAAM,cAAc,EAAE,aAAoC,CAAC;AAElE,gFAAgF;AAChF,eAAO,MAAM,aAAa,EAAE,aAAmC,CAAC"}

package/dist/tools/config.js

@@ -0,0 +1,104 @@
+/**
+ * @file Real `save_config` / `get_config` tool modules (T022, US-0).
+ *
+ * These two tools own the first-run setup gate's lifecycle: `save_config` writes
+ * the `config` block that clears the gate (FR-031/032) and `get_config` reports
+ * gate state. Both are exempt from {@link withSetupGate} (see
+ * {@link EXEMPT_TOOLS}) — gating them would deadlock setup.
+ *
+ * Clock note: the engine stays pure, but these tools live in the IO/tool layer,
+ * so they MAY read the wall clock to stamp `createdAt`/`updatedAt`
+ * (`new Date().toISOString()`). The store's atomic read-modify-write
+ * ({@link updateProfile}) is reused so a re-config never races a concurrent
+ * writer, and only the `config` field is replaced — abilities, graduations,
+ * review schedule, quiz history, and offer state are preserved (FR-033).
+ *
+ * Each tool is exposed as a factory closing over an optional `dirOverride`
+ * (the store's test seam): the registry uses the default instances (env /
+ * `~/.vibe-hero`), and tests build dir-scoped instances against a temp home.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md
+ * (`save_config` / `get_config`), spec.md FR-031 / FR-032 / FR-033.
+ */
+import { loadProfile, updateProfile } from "../profile/store.js";
+import { ConfigSchema } from "../schemas/profile.js";
+import { GetConfigInputSchema, SaveConfigInputSchema, } from "../schemas/tools.js";
+import { defineTool } from "./types.js";
+/**
+ * Normalize validated `save_config` input into a persisted {@link Config},
+ * preserving `createdAt` from any existing config and stamping `updatedAt`
+ * (and a first-write `createdAt`) to `now`.
+ *
+ * `quizLength` is optional on input; {@link ConfigSchema} supplies its default
+ * (4) when absent. Parsing through `ConfigSchema` guarantees the result matches
+ * the persisted contract before it ever reaches the store.
+ *
+ * @param input - Validated `save_config` input.
+ * @param existing - The current config, if the profile is already configured.
+ * @param now - ISO-8601 timestamp for `updatedAt` (and `createdAt` on first save).
+ * @returns A schema-valid {@link Config} ready to persist.
+ */
+const normalizeConfig = (input, existing, now) => ConfigSchema.parse({
+    toolsLearning: input.toolsLearning,
+    offerCadence: input.offerCadence,
+    proactiveOffers: input.proactiveOffers,
+    // Omit when absent so ConfigSchema applies its default (4); otherwise honor it.
+    ...(input.quizLength !== undefined ? { quizLength: input.quizLength } : {}),
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+});
+/**
+ * Build the `save_config` tool module (US-0, FR-031/033).
+ *
+ * Validates input, then atomically replaces only the profile's `config` block
+ * via {@link updateProfile}. Because every other field is spread through
+ * untouched, re-running setup updates preferences without losing learning
+ * progress (FR-033). Returns `{ ok: true, config }` with the persisted config.
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @returns The erased registry entry for `save_config`.
+ */
+export const makeSaveConfigTool = (dirOverride) => defineTool({
+    name: "save_config",
+    description: "Persist setup configuration and clear the setup gate. Re-callable to update preferences.",
+    inputSchema: SaveConfigInputSchema,
+    handler: async (input) => {
+        const now = new Date().toISOString();
+        const next = await updateProfile((current) => ({
+            ...current,
+            config: normalizeConfig(input, current.config, now),
+        }), dirOverride);
+        // `config` is always present here (we just wrote it); assert for the type.
+        const config = next.config;
+        if (config === undefined) {
+            throw new Error("save_config: profile.config missing after write");
+        }
+        return { ok: true, config };
+    },
+});
+/**
+ * Build the `get_config` tool module (US-0).
+ *
+ * Reads the profile (never throws — a missing/corrupt profile degrades to an
+ * unconfigured one) and reports whether `config` is present, echoing it when so.
+ * Skills/hooks use this to know the gate state without triggering it.
+ *
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @returns The erased registry entry for `get_config`.
+ */
+export const makeGetConfigTool = (dirOverride) => defineTool({
+    name: "get_config",
+    description: "Read the current configuration (or report its absence / gate state).",
+    inputSchema: GetConfigInputSchema,
+    handler: async () => {
+        const profile = await loadProfile(dirOverride);
+        return profile.config === undefined
+            ? { configured: false }
+            : { configured: true, config: profile.config };
+    },
+});
+/** Default `save_config` module (env / `~/.vibe-hero`), used by the registry. */
+export const saveConfigTool = makeSaveConfigTool();
+/** Default `get_config` module (env / `~/.vibe-hero`), used by the registry. */
+export const getConfigTool = makeGetConfigTool();
+//# sourceMappingURL=config.js.map

package/dist/tools/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/tools/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,YAAY,EAA6B,MAAM,uBAAuB,CAAC;AAChF,OAAO,EACL,oBAAoB,EACpB,qBAAqB,GAItB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAsB,MAAM,YAAY,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,eAAe,GAAG,CACtB,KAAsB,EACtB,QAA4B,EAC5B,GAAW,EACH,EAAE,CACV,YAAY,CAAC,KAAK,CAAC;IACjB,aAAa,EAAE,KAAK,CAAC,aAAa;IAClC,YAAY,EAAE,KAAK,CAAC,YAAY;IAChC,eAAe,EAAE,KAAK,CAAC,eAAe;IACtC,gFAAgF;IAChF,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,SAAS,EAAE,QAAQ,EAAE,SAAS,IAAI,GAAG;IACrC,SAAS,EAAE,GAAG;CACf,CAAC,CAAC;AAEL;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,WAAoB,EAAiB,EAAE,CACxE,UAAU,CAAC;IACT,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,0FAA0F;IAC5F,WAAW,EAAE,qBAAqB;IAClC,OAAO,EAAE,KAAK,EAAE,KAAK,EAA6B,EAAE;QAClD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,IAAI,GAAY,MAAM,aAAa,CACvC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACZ,GAAG,OAAO;YACV,MAAM,EAAE,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpD,CAAC,EACF,WAAW,CACZ,CAAC;QACF,2EAA2E;QAC3E,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC9B,CAAC;CACF,CAAC,CAAC;AAEL;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,WAAoB,EAAiB,EAAE,CACvE,UAAU,CAAC;IACT,IAAI,EAAE,YAAY;IAClB,WAAW,EACT,sEAAsE;IACxE,WAAW,EAAE,oBAAoB;IACjC,OAAO,EAAE,KAAK,IAA8B,EAAE;QAC5C,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC,CAAC;QAC/C,OAAO,OAAO,CAAC,MAAM,KAAK,SAAS;YACjC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE;YACvB,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IACnD,CAAC;CACF,CAAC,CAAC;AAEL,iFAAiF;AACjF,MAAM,CAAC,MAAM,cAAc,GAAkB,kBAAkB,EAAE,CAAC;AAElE,gFAAgF;AAChF,MAAM,CAAC,MAAM,aAAa,GAAkB,iBAAiB,EAAE,CAAC"}

package/dist/tools/gate.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file Setup-gate wrapper for MCP tool handlers (T021).
+ *
+ * Every vibe-hero tool except `get_config` / `save_config` is gated behind
+ * first-run setup: until the learner profile has a `config` block, a gated tool
+ * returns the {@link SETUP_REQUIRED_RESULT} sentinel instead of running its
+ * handler (FR-032). This scopes the gate to vibe-hero's own actions only — it
+ * never blocks the host agent's normal work (FR-028).
+ *
+ * The two exempt tools are exactly the ones the setup skill needs to *clear* the
+ * gate (`save_config`) and to *inspect* gate state (`get_config`); gating those
+ * would deadlock setup.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md (SETUP_REQUIRED
+ * sentinel), spec.md FR-028 / FR-032.
+ */
+import type { SetupRequired } from "../schemas/tools.js";
+import type { ToolHandler } from "./types.js";
+/**
+ * Tools that bypass the setup gate. `get_config` reports gate state and
+ * `save_config` writes the `config` that clears the gate, so both must run
+ * before setup completes. Every other tool is gated.
+ */
+export declare const EXEMPT_TOOLS: ReadonlySet<string>;
+/** Is `toolName` allowed to run while the profile is unconfigured? */
+export declare const isExempt: (toolName: string) => boolean;
+/**
+ * The canonical SETUP_REQUIRED sentinel returned by gated tools when
+ * `profile.config` is absent. Validated against {@link SetupRequiredSchema} at
+ * module load so the shape can never drift from the contract.
+ */
+export declare const SETUP_REQUIRED_RESULT: SetupRequired;
+/**
+ * Wrap a tool handler with the first-run setup gate (FR-032).
+ *
+ * Before invoking `handler`, the wrapper loads the profile. If the tool is not
+ * exempt ({@link EXEMPT_TOOLS}) and `profile.config` is absent, it short-circuits
+ * with {@link SETUP_REQUIRED_RESULT} and the handler never runs. Otherwise the
+ * handler runs normally.
+ *
+ * `loadProfile` never throws (a missing/corrupt profile degrades to an empty,
+ * unconfigured profile), so an unconfigured first run reliably gates.
+ *
+ * @param toolName - The tool's registered name (used for the exempt check).
+ * @param handler - The wrapped tool handler.
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @returns A handler that enforces the gate before delegating.
+ */
+export declare const withSetupGate: <Args>(toolName: string, handler: ToolHandler<Args>, dirOverride?: string) => ToolHandler<Args>;
+//# sourceMappingURL=gate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/tools/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,YAAY,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,CAG3C,CAAC;AAEH,sEAAsE;AACtE,eAAO,MAAM,QAAQ,GAAI,UAAU,MAAM,KAAG,OAAqC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAIlC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,EAChC,UAAU,MAAM,EAChB,SAAS,WAAW,CAAC,IAAI,CAAC,EAC1B,cAAc,MAAM,KACnB,WAAW,CAAC,IAAI,CAUlB,CAAC"}

package/dist/tools/gate.js

@@ -0,0 +1,67 @@
+/**
+ * @file Setup-gate wrapper for MCP tool handlers (T021).
+ *
+ * Every vibe-hero tool except `get_config` / `save_config` is gated behind
+ * first-run setup: until the learner profile has a `config` block, a gated tool
+ * returns the {@link SETUP_REQUIRED_RESULT} sentinel instead of running its
+ * handler (FR-032). This scopes the gate to vibe-hero's own actions only — it
+ * never blocks the host agent's normal work (FR-028).
+ *
+ * The two exempt tools are exactly the ones the setup skill needs to *clear* the
+ * gate (`save_config`) and to *inspect* gate state (`get_config`); gating those
+ * would deadlock setup.
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/contracts/mcp-tools.md (SETUP_REQUIRED
+ * sentinel), spec.md FR-028 / FR-032.
+ */
+import { SetupRequiredSchema } from "../schemas/tools.js";
+import { loadProfile } from "../profile/store.js";
+/**
+ * Tools that bypass the setup gate. `get_config` reports gate state and
+ * `save_config` writes the `config` that clears the gate, so both must run
+ * before setup completes. Every other tool is gated.
+ */
+export const EXEMPT_TOOLS = new Set([
+    "get_config",
+    "save_config",
+]);
+/** Is `toolName` allowed to run while the profile is unconfigured? */
+export const isExempt = (toolName) => EXEMPT_TOOLS.has(toolName);
+/**
+ * The canonical SETUP_REQUIRED sentinel returned by gated tools when
+ * `profile.config` is absent. Validated against {@link SetupRequiredSchema} at
+ * module load so the shape can never drift from the contract.
+ */
+export const SETUP_REQUIRED_RESULT = SetupRequiredSchema.parse({
+    status: "SETUP_REQUIRED",
+    message: "Run vibe-hero setup first.",
+    setupSkill: "vibe-hero-setup",
+});
+/**
+ * Wrap a tool handler with the first-run setup gate (FR-032).
+ *
+ * Before invoking `handler`, the wrapper loads the profile. If the tool is not
+ * exempt ({@link EXEMPT_TOOLS}) and `profile.config` is absent, it short-circuits
+ * with {@link SETUP_REQUIRED_RESULT} and the handler never runs. Otherwise the
+ * handler runs normally.
+ *
+ * `loadProfile` never throws (a missing/corrupt profile degrades to an empty,
+ * unconfigured profile), so an unconfigured first run reliably gates.
+ *
+ * @param toolName - The tool's registered name (used for the exempt check).
+ * @param handler - The wrapped tool handler.
+ * @param dirOverride - Profile-directory override (test seam); see `profileDir`.
+ * @returns A handler that enforces the gate before delegating.
+ */
+export const withSetupGate = (toolName, handler, dirOverride) => {
+    return async (args) => {
+        if (!isExempt(toolName)) {
+            const profile = await loadProfile(dirOverride);
+            if (profile.config === undefined) {
+                return SETUP_REQUIRED_RESULT;
+            }
+        }
+        return handler(args);
+    };
+};
+//# sourceMappingURL=gate.js.map

package/dist/tools/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/tools/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC;IACvD,YAAY;IACZ,aAAa;CACd,CAAC,CAAC;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAgB,EAAW,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAElF;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAkB,mBAAmB,CAAC,KAAK,CAAC;IAC5E,MAAM,EAAE,gBAAgB;IACxB,OAAO,EAAE,4BAA4B;IACrC,UAAU,EAAE,iBAAiB;CAC9B,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,QAAgB,EAChB,OAA0B,EAC1B,WAAoB,EACD,EAAE;IACrB,OAAO,KAAK,EAAE,IAAU,EAAuB,EAAE;QAC/C,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxB,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC,CAAC;YAC/C,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBACjC,OAAO,qBAAqB,CAAC;YAC/B,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC,CAAC"}

package/dist/tools/guidance.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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 { type AnyToolModule } from "./types.js";
+/**
+ * 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 declare const makeGetGuidanceTool: (dirOverride?: string) => AnyToolModule;
+/** Default `get_guidance` module (env / `~/.vibe-hero`), used by the registry. */
+export declare const getGuidanceTool: AnyToolModule;
+//# sourceMappingURL=guidance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.d.ts","sourceRoot":"","sources":["../../src/tools/guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAiBH,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAuG5D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,cAAc,MAAM,KAAG,aAYvD,CAAC;AAEL,kFAAkF;AAClF,eAAO,MAAM,eAAe,EAAE,aAAqC,CAAC"}