handzon-core 0.6.2 → 0.8.0

package/src/lib/ai/prompts.ts

@@ -0,0 +1,126 @@
+import type { ChatMessage } from "./client";
+import type { AssistantContext } from "./context";
+
+export type AssistantIntent =
+  | { kind: "unstuck"; topic?: string }
+  | {
+      kind: "quizFix";
+      question: string;
+      chosen: string[];
+      correct: string[];
+    }
+  | { kind: "checkpoint"; label: string }
+  | { kind: "selection"; text: string }
+  | { kind: "playgroundFix"; files: Record<string, string> }
+  | { kind: "explainStep" }
+  | { kind: "recap" };
+
+export interface AssistantPrompt {
+  /** Ready-to-render Markdown a learner can paste anywhere. */
+  markdown: string;
+  /** Seed messages for ChatPanel — first user turn, no assistant turn. */
+  seedMessages: ChatMessage[];
+  /** URL-encoded prompt for each external agent. */
+  deepLinks: {
+    cursor: string;
+    claude: string;
+    chatgpt: string;
+    vscode: string;
+  };
+}
+
+function header(ctx: AssistantContext): string {
+  return [`Tutorial: ${ctx.tutorial.title}`, `Step: ${ctx.currentStep.title}`].join("\n");
+}
+
+function renderIntent(ctx: AssistantContext, intent: AssistantIntent): string {
+  switch (intent.kind) {
+    case "unstuck":
+      return intent.topic
+        ? `I'm stuck on "${intent.topic}". Help me figure out what to do next without giving the whole answer.`
+        : `I'm stuck on this step. Help me figure out what to do next without giving the whole answer.`;
+    case "quizFix":
+      return [
+        `I got a quiz question wrong and want to understand why.`,
+        ``,
+        `Question: ${intent.question}`,
+        `I chose: ${intent.chosen.join(", ") || "(nothing)"}`,
+        `Correct answer: ${intent.correct.join(", ")}`,
+        ``,
+        `Explain why my choice is wrong without restating the correct answer verbatim — help me see what concept I'm missing.`,
+      ].join("\n");
+    case "checkpoint":
+      return `I'm not sure how to complete this checkpoint: "${intent.label}". Walk me through what to try next.`;
+    case "selection":
+      return [
+        `I have a question about this part of the tutorial:`,
+        ``,
+        "```",
+        intent.text,
+        "```",
+        ``,
+        `Can you explain it in context of where I am?`,
+      ].join("\n");
+    case "playgroundFix": {
+      const files = Object.entries(intent.files)
+        .map(([path, body]) => `### \`${path}\`\n\n\`\`\`\n${body}\n\`\`\``)
+        .join("\n\n");
+      return [
+        `My playground code isn't working as expected. Here are the current files:`,
+        ``,
+        files,
+        ``,
+        `What's wrong, and what should I change? Point me at the bug; don't just rewrite the file.`,
+      ].join("\n");
+    }
+    case "explainStep":
+      return [
+        `Walk me through what this step is asking me to do and why it matters.`,
+        ``,
+        `Step content:`,
+        ``,
+        ctx.currentStep.source,
+      ].join("\n");
+    case "recap":
+      return `Give me a one-paragraph recap of what I've learned so far in this tutorial.`;
+  }
+}
+
+function buildMarkdown(ctx: AssistantContext, intent: AssistantIntent): string {
+  return [header(ctx), "", renderIntent(ctx, intent)].join("\n");
+}
+
+/**
+ * Cursor's anysphere deep link expects a `text` query param.
+ * Claude.ai and ChatGPT use `?q=...`. VS Code can launch a chat
+ * extension via the `vscode://` scheme; we use the generic
+ * `vscode://GitHub.copilot-chat/chat?prompt=...` form, which is
+ * the closest thing to a stable contract today.
+ */
+function buildDeepLinks(prompt: string): AssistantPrompt["deepLinks"] {
+  const enc = encodeURIComponent(prompt);
+  return {
+    cursor: `cursor://anysphere.cursor-deeplink/prompt?text=${enc}`,
+    claude: `https://claude.ai/new?q=${enc}`,
+    chatgpt: `https://chat.openai.com/?q=${enc}`,
+    vscode: `vscode://GitHub.copilot-chat/chat?prompt=${enc}`,
+  };
+}
+
+/**
+ * Render an assistant context + a small intent payload into the three
+ * surfaces every touchpoint needs: chat seed messages, copyable
+ * markdown, and per-agent deep links. Each Family A/B touchpoint is a
+ * one-liner around this function.
+ */
+export function buildAssistantPrompt(
+  context: AssistantContext,
+  intent: AssistantIntent,
+): AssistantPrompt {
+  const markdown = buildMarkdown(context, intent);
+  return {
+    markdown,
+    seedMessages: [{ role: "user", content: markdown }],
+    deepLinks: buildDeepLinks(markdown),
+  };
+}

package/src/lib/ai/stepData.ts

@@ -0,0 +1,74 @@
+import type { AssistantContext } from "./context";
+
+/**
+ * Reads the per-step JSON payload that TutorialLayout emits into
+ * `<script id="tt-step-data" type="application/json">`. Family B
+ * touchpoints (CopyPrompt, deep-link row, copy-step button, …) need
+ * the raw MDX source and tutorial/step titles at click time without
+ * having every island accept them as props.
+ */
+export interface StepData {
+  tutorialSlug: string;
+  tutorialTitle: string;
+  stepSlug: string;
+  stepTitle: string;
+  stepSource: string;
+}
+
+export function readStepData(): StepData | null {
+  if (typeof document === "undefined") return null;
+  const node = document.getElementById("tt-step-data");
+  if (!node?.textContent) return null;
+  try {
+    return JSON.parse(node.textContent) as StepData;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render a CopyPrompt template by substituting `{{placeholder}}`
+ * tokens with the values from step data. Unknown placeholders are
+ * left untouched so authors notice typos.
+ */
+export function renderTemplate(template: string, data: StepData): string {
+  const map: Record<string, string> = {
+    tutorialTitle: data.tutorialTitle,
+    tutorialSlug: data.tutorialSlug,
+    stepTitle: data.stepTitle,
+    stepSlug: data.stepSlug,
+    stepSource: data.stepSource,
+  };
+  return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (raw, key) => {
+    return key in map ? map[key] : raw;
+  });
+}
+
+/**
+ * Construct a minimal AssistantContext from client-side step data
+ * for Family B touchpoints that need to call buildAssistantPrompt
+ * without the build-time context that ChatButton holds. Fields we
+ * don't know client-side (difficulty, tags, outline, prior steps,
+ * progress) come back empty; the intents that Family B uses
+ * (explainStep, recap) only read tutorial + currentStep.
+ */
+export function contextFromStepData(data: StepData): AssistantContext {
+  return {
+    tutorial: {
+      slug: data.tutorialSlug,
+      title: data.tutorialTitle,
+      description: "",
+      difficulty: "",
+      tags: [],
+    },
+    outline: [],
+    currentStep: {
+      slug: data.stepSlug,
+      title: data.stepTitle,
+      source: data.stepSource,
+    },
+    priorSteps: [],
+    progress: { completed: [], quizzes: [], checkpoints: [] },
+    references: [],
+  };
+}

package/src/lib/mdx-components.ts

@@ -1,10 +1,12 @@
 import Callout from "../components/mdx/Callout.astro";
 import Checkpoint from "../components/mdx/Checkpoint.astro";
+import CopyPrompt from "../components/mdx/CopyPrompt.astro";
 import Diff from "../components/mdx/Diff.astro";
 import Download from "../components/mdx/Download.astro";
 import Embed from "../components/mdx/Embed.astro";
 import File from "../components/mdx/File.astro";
 import FileTree from "../components/mdx/FileTree.astro";
+import HelpMe from "../components/mdx/HelpMe.astro";
 import Hint from "../components/mdx/Hint.astro";
 import Mermaid from "../components/mdx/Mermaid.astro";
 import Playground from "../components/mdx/Playground.astro";
@@ -43,5 +45,7 @@ export function mdxComponents() {
     Quiz,
     Checkpoint,
     Playground,
+    HelpMe,
+    CopyPrompt,
   };
 }

package/src/lib/progress/remote.ts

@@ -65,6 +65,21 @@ function diffState(prev: ProgressState, next: ProgressState): ProgressEntry[] {
       out.push({ kind: "checkpoint", scope: "global", key: id, value });
     }
   }
+  // Emit deletions so the server tombstones unchecked checkpoints; without
+  // this the next snapshot fetch would resurrect them from the DB.
+  for (const id of Object.keys(prev.checkpoints)) {
+    if (!next.checkpoints[id]) {
+      out.push({ kind: "checkpoint", scope: "global", key: id, value: null });
+      // Family D: drop the matching kind:"verification" telemetry
+      // row so a re-attempt isn't pre-poisoned by the previous
+      // failure feedback. Scope comes from the feedback entry
+      // populated by SSE.
+      const feedback = prev.verificationFeedback[id];
+      if (feedback) {
+        out.push({ kind: "verification", scope: feedback.scope, key: id, value: null });
+      }
+    }
+  }
   for (const [k, value] of Object.entries(next.prefs)) {
     if ((prev.prefs as Record<string, unknown>)[k] !== value) {
       out.push({ kind: "pref", scope: "global", key: k, value });
@@ -88,6 +103,59 @@ function diffState(prev: ProgressState, next: ProgressState): ProgressEntry[] {
   return out;
 }
 
+/**
+ * Apply one server-side progress entry to a mutable state object.
+ * Shared by the initial snapshot fetch and the SSE per-event path.
+ * Mutates in place — callers replace the store atom after batching.
+ */
+function applyEntryInto(state: ProgressState, e: ProgressEntry): void {
+  if (e.kind === "step") {
+    state.steps[`${e.scope}/${e.key}` as `${string}/${string}`] = e.value as
+      | "incomplete"
+      | "complete";
+  } else if (e.kind === "quiz") {
+    state.quizzes[e.key] = e.value as ProgressState["quizzes"][string];
+  } else if (e.kind === "checkpoint") {
+    if (e.value == null) {
+      delete state.checkpoints[e.key];
+      return;
+    }
+    state.checkpoints[e.key] = e.value as ProgressState["checkpoints"][string];
+  } else if (e.kind === "pref") {
+    (state.prefs as Record<string, unknown>)[e.key] = e.value;
+  } else if (e.kind === "lastVisited") {
+    const v = e.value as unknown;
+    state.lastVisited[e.scope] =
+      typeof v === "string" ? { step: v, ts: 0 } : (v as { step: string; ts: number });
+  } else if (e.kind === "tutorial") {
+    const v = (e.value as { ts?: number }) ?? {};
+    const marker = state.tutorials[e.scope] ?? {};
+    if (e.key === "started") marker.started = v.ts;
+    else if (e.key === "completed") marker.completed = v.ts;
+    state.tutorials[e.scope] = marker;
+  } else if (e.kind === "verification") {
+    if (e.value == null) {
+      delete state.verificationFeedback[e.key];
+      return;
+    }
+    const v = e.value as {
+      pass: boolean;
+      failingCheckIndex?: number;
+      reason?: string;
+      hint?: string;
+      ts?: number;
+    };
+    state.verificationFeedback[e.key] = {
+      scope: e.scope as `${string}/${string}`,
+      pass: !!v.pass,
+      failingCheckIndex: v.failingCheckIndex,
+      reason: v.reason,
+      hint: v.hint,
+      ts: v.ts ?? Date.now(),
+    };
+  }
+}
+
 /**
  * Same shape as the local store, but mirrors writes to /api/progress with
  * debounced batching and an offline queue.
@@ -142,30 +210,7 @@ export function createRemoteStore(): ProgressStore {
           entries: Array<{ kind: string; scope: string; key: string; value: unknown }>;
         };
         const merged: ProgressState = { ...emptyState(), ...state };
-        for (const e of entries) {
-          if (e.kind === "step") {
-            merged.steps[`${e.scope}/${e.key}` as `${string}/${string}`] = e.value as
-              | "incomplete"
-              | "complete";
-          } else if (e.kind === "quiz") {
-            merged.quizzes[e.key] = e.value as ProgressState["quizzes"][string];
-          } else if (e.kind === "checkpoint") {
-            merged.checkpoints[e.key] = e.value as ProgressState["checkpoints"][string];
-          } else if (e.kind === "pref") {
-            (merged.prefs as Record<string, unknown>)[e.key] = e.value;
-          } else if (e.kind === "lastVisited") {
-            // Tolerate both new ({step, ts}) and legacy (string) shapes.
-            const v = e.value as unknown;
-            merged.lastVisited[e.scope] =
-              typeof v === "string" ? { step: v, ts: 0 } : (v as { step: string; ts: number });
-          } else if (e.kind === "tutorial") {
-            const v = (e.value as { ts?: number }) ?? {};
-            const marker = merged.tutorials[e.scope] ?? {};
-            if (e.key === "started") marker.started = v.ts;
-            else if (e.key === "completed") marker.completed = v.ts;
-            merged.tutorials[e.scope] = marker;
-          }
-        }
+        for (const e of entries) applyEntryInto(merged, e);
         state = merged;
         writeStorage(state);
         for (const fn of subscribers) fn(state);
@@ -173,6 +218,30 @@ export function createRemoteStore(): ProgressStore {
         // ignore — local data still drives the UI
       }
     })();
+
+    // Live sync: subscribe to per-learner SSE so MCP-driven writes
+    // (or another tab via the cookie POST) show up immediately. The
+    // standard EventSource auto-reconnects on transient drops.
+    if (typeof EventSource !== "undefined") {
+      try {
+        const es = new EventSource("/api/progress/events", { withCredentials: true });
+        es.addEventListener("message", (ev) => {
+          try {
+            const entry = JSON.parse(ev.data) as ProgressEntry;
+            const next: ProgressState = { ...state };
+            applyEntryInto(next, entry);
+            state = next;
+            writeStorage(state);
+            for (const fn of subscribers) fn(state);
+            channel?.postMessage({ type: "set", state });
+          } catch (e) {
+            console.warn("[handzon] sse parse failed:", e);
+          }
+        });
+      } catch {
+        // ignore — polling-via-mount still keeps things eventually consistent
+      }
+    }
   }
 
   return {

package/src/lib/progress/types.ts

@@ -16,10 +16,32 @@ export interface TutorialMarker {
   completed?: number;
 }
 
+/**
+ * Family D verification feedback delivered via SSE from
+ * `submit_verification` failures. Keyed by the checkpoint id (which
+ * equals `verify.id`). Carries the step scope so the diff can emit
+ * a tombstone with the right scope when the learner unchecks.
+ */
+export interface VerificationFeedbackEntry {
+  scope: StepKey;
+  pass: boolean;
+  failingCheckIndex?: number;
+  reason?: string;
+  hint?: string;
+  ts: number;
+}
+
 export type ProgressState = {
   steps: Record<StepKey, "incomplete" | "complete">;
   quizzes: Record<string, { chosen: number[]; correct: boolean; ts: number }>;
   checkpoints: Record<string, { ts: number }>;
+  /**
+   * Latest verification verdict per checkpoint id. `pass: true`
+   * entries hang around as evidence; the Family D UI only renders
+   * the inline hint block on `pass: false`. Cleared when the
+   * learner unchecks the matching checkpoint.
+   */
+  verificationFeedback: Record<string, VerificationFeedbackEntry>;
   prefs: {
     packageManager?: "npm" | "pnpm" | "yarn" | "bun";
     os?: "macos" | "linux" | "windows";
@@ -50,6 +72,7 @@ export const emptyState = (): ProgressState => ({
   steps: {},
   quizzes: {},
   checkpoints: {},
+  verificationFeedback: {},
   prefs: {},
   lastVisited: {},
   tutorials: {},

package/src/lib/progress/useProgress.ts

@@ -8,6 +8,7 @@ interface ProgressApi {
   markStepIncomplete: (tutorial: string, step: string) => void;
   recordQuiz: (questionId: string, chosen: number[], correct: boolean) => void;
   recordCheckpoint: (checkpointId: string) => void;
+  removeCheckpoint: (checkpointId: string) => void;
   setPref: <K extends keyof ProgressState["prefs"]>(
     key: K,
     value: ProgressState["prefs"][K],
@@ -56,6 +57,17 @@ export function useProgress(): ProgressApi {
           ...s,
           checkpoints: { ...s.checkpoints, [checkpointId]: { ts: Date.now() } },
         })),
+      removeCheckpoint: (checkpointId: string) =>
+        store.set((s) => {
+          const hadCheckpoint = !!s.checkpoints[checkpointId];
+          const hadFeedback = !!s.verificationFeedback[checkpointId];
+          if (!hadCheckpoint && !hadFeedback) return s;
+          const nextCheckpoints = { ...s.checkpoints };
+          delete nextCheckpoints[checkpointId];
+          const nextFeedback = { ...s.verificationFeedback };
+          delete nextFeedback[checkpointId];
+          return { ...s, checkpoints: nextCheckpoints, verificationFeedback: nextFeedback };
+        }),
       setPref: <K extends keyof ProgressState["prefs"]>(key: K, value: ProgressState["prefs"][K]) =>
         store.set((s) => ({ ...s, prefs: { ...s.prefs, [key]: value } })),
       setLastVisited: (tutorial: string, step: string) =>

package/src/pages/TutorialStep.astro

@@ -2,6 +2,9 @@
 import { render } from "astro:content";
 import TutorialLayout from "../layouts/TutorialLayout.astro";
 import ChatButton from "../components/ai/ChatButton.tsx";
+import OpenInAgent from "../components/ai/OpenInAgent.tsx";
+import SelectionAsk from "../components/ai/SelectionAsk.tsx";
+import StepHelp from "../components/ai/StepHelp.tsx";
 import { parseStepId } from "../lib/content.ts";
 import type { StepEntry, TutorialEntry } from "../lib/content.ts";
 import { mdxComponents } from "../lib/mdx-components.ts";
@@ -61,7 +64,15 @@ const initialContext = buildContext({
   repoUrl={repoUrl}
 >
   <Content components={components} />
+  {aiConfig.enabled && aiConfig.autoStepHelp && (
+    <StepHelp client:visible stepTitle={currentStep.data.title} />
+  )}
+  <OpenInAgent client:visible />
+
   {aiConfig.enabled && (
-    <ChatButton client:idle config={aiConfig} context={initialContext} />
+    <>
+      <ChatButton client:idle config={aiConfig} context={initialContext} />
+      <SelectionAsk client:idle />
+    </>
   )}
 </TutorialLayout>

package/src/pages/paths.ts

@@ -5,8 +5,9 @@
  *   export const getStaticPaths = getTutorialLandingPaths;
  *   export const getStaticPaths = getTutorialStepPaths;
  */
-import { getStepsForTutorial, getTutorials, parseStepId } from "../lib/content.ts";
+
 import type { StepEntry, TutorialEntry } from "../lib/content.ts";
+import { getStepsForTutorial, getTutorials, parseStepId } from "../lib/content.ts";
 
 export async function getTutorialLandingPaths() {
   const tutorials = await getTutorials();

package/src/server/auth/config.ts

@@ -10,8 +10,9 @@
  * GitHub is the only provider in 0.2; email/password and others are
  * out of scope (see plan: github-auth_d52529d5).
  */
-import { DrizzleAdapter } from "@auth/drizzle-adapter";
+
 import GitHub from "@auth/core/providers/github";
+import { DrizzleAdapter } from "@auth/drizzle-adapter";
 import { defineConfig } from "auth-astro";
 import { accounts, sessions, users, verificationTokens } from "./schema.ts";
 

package/src/server/auth/schema.ts

@@ -6,14 +6,7 @@
  * The `learners` row that maps a signed-in user to local progress lives
  * in `../db/schema.ts` — it adds a nullable `user_id` FK to `users` here.
  */
-import {
-  integer,
-  pgTable,
-  primaryKey,
-  text,
-  timestamp,
-  uuid,
-} from "drizzle-orm/pg-core";
+import { integer, pgTable, primaryKey, text, timestamp, uuid } from "drizzle-orm/pg-core";
 
 export const users = pgTable("users", {
   id: uuid("id").primaryKey().defaultRandom(),

package/src/server/auth.ts

@@ -2,7 +2,7 @@ import type { AstroCookieSetOptions, AstroCookies } from "astro";
 import { and, eq, isNull } from "drizzle-orm";
 import { getAuthedUser } from "./auth/session.ts";
 import { getDb } from "./db/client.ts";
-import { learners, progressEntries } from "./db/schema.ts";
+import { learnerApiTokens, learners, progressEntries } from "./db/schema.ts";
 
 const COOKIE = "tt-device";
 const ONE_YEAR = 60 * 60 * 24 * 365;
@@ -61,11 +61,7 @@ export async function getOrCreateLearner(
   // Anonymous path — unchanged from pre-auth behaviour.
   let deviceId = cookies.get(COOKIE)?.value;
   if (deviceId) {
-    const found = await db
-      .select()
-      .from(learners)
-      .where(eq(learners.deviceId, deviceId))
-      .limit(1);
+    const found = await db.select().from(learners).where(eq(learners.deviceId, deviceId)).limit(1);
     if (found[0]) return { id: found[0].id, deviceId };
   }
   deviceId = randomDeviceId();
@@ -125,3 +121,86 @@ async function maybeClaimDeviceProgress(
     await tx.delete(learners).where(eq(learners.id, orphan.id));
   });
 }
+
+const PAT_PREFIX = "hzn_pat_";
+const PAT_RANDOM_BYTES = 32;
+
+/** Hash a raw PAT string to its database form. SHA-256 hex. */
+export async function hashPat(raw: string): Promise<string> {
+  const data = new TextEncoder().encode(raw);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Generate a fresh PAT to show the learner once. The settings page is
+ * the only caller — the API surface never sees the raw token after
+ * mint, and only the hash hits the database.
+ */
+export function generatePat(): string {
+  const bytes = new Uint8Array(PAT_RANDOM_BYTES);
+  crypto.getRandomValues(bytes);
+  // Base64url without padding — agent config files want short, copy/pasteable tokens.
+  const b64 = btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return `${PAT_PREFIX}${b64}`;
+}
+
+/**
+ * Resolve a bearer token presented on an incoming request to the
+ * learner that owns it. Returns null when no token, the token is
+ * unknown, or it has expired. `last_used_at` is touched
+ * asynchronously so a slow DB write doesn't add latency to MCP calls.
+ *
+ * Used by the MCP endpoint; the cookie-based progress endpoint stays
+ * on getOrCreateLearner so the same-origin guard remains effective.
+ */
+export async function resolveBearerLearner(
+  request: Request,
+): Promise<{ learnerId: string; scopes: string[] } | null> {
+  const header = request.headers.get("authorization") ?? request.headers.get("Authorization");
+  if (!header) return null;
+  const match = /^Bearer\s+(\S+)$/i.exec(header.trim());
+  if (!match) return null;
+  const raw = match[1]!;
+  if (!raw.startsWith(PAT_PREFIX)) return null;
+
+  const db = getDb();
+  const hash = await hashPat(raw);
+  const rows = await db
+    .select()
+    .from(learnerApiTokens)
+    .where(eq(learnerApiTokens.tokenHash, hash))
+    .limit(1);
+  const token = rows[0];
+  if (!token) return null;
+  if (token.expiresAt && token.expiresAt.getTime() < Date.now()) return null;
+
+  const learnerRow = await db
+    .select({ id: learners.id })
+    .from(learners)
+    .where(eq(learners.userId, token.userId))
+    .limit(1);
+  const learner = learnerRow[0];
+  if (!learner) return null;
+
+  // Fire-and-forget last-used touch. Failures are logged-but-ignored;
+  // an audit log is more useful than blocking the call.
+  void db
+    .update(learnerApiTokens)
+    .set({ lastUsedAt: new Date() })
+    .where(eq(learnerApiTokens.id, token.id))
+    .catch((e) => {
+      console.warn("[handzon] failed to update PAT last_used_at:", e);
+    });
+
+  const scopes = token.scopes
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return { learnerId: learner.id, scopes };
+}

package/src/server/db/schema.ts

@@ -13,7 +13,7 @@ import { users } from "../auth/schema.ts";
 
 // Re-export the Auth.js tables so consumers (and drizzle-kit) see one
 // schema barrel.
-export { users, accounts, sessions, verificationTokens } from "../auth/schema.ts";
+export { accounts, sessions, users, verificationTokens } from "../auth/schema.ts";
 
 export const learners = pgTable(
   "learners",
@@ -40,6 +40,59 @@ export const learners = pgTable(
   }),
 );
 
+/**
+ * Personal access tokens for the per-user MCP surface.
+ *
+ * Created by the settings/tokens page in the scaffold template. Stored
+ * as SHA-256 hashes of `hzn_pat_<32 base64url bytes>` strings — the
+ * raw token is shown to the learner once at mint time and never
+ * persisted. The MCP v2 OAuth proxy reuses this table, so the row
+ * shape is forward-compatible with DCR-minted tokens.
+ *
+ * scopes: comma-separated; v1 known values are "progress:read" and
+ * "progress:write". Catalog reads don't require any scope beyond a
+ * valid token.
+ */
+export const learnerApiTokens = pgTable("learner_api_tokens", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  name: text("name").notNull(),
+  tokenHash: text("token_hash").notNull().unique(),
+  scopes: text("scopes").notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+  expiresAt: timestamp("expires_at", { withTimezone: true }),
+});
+
+/**
+ * Help-bridge inbox: pending help requests posted by the agent on
+ * the learner's machine (`request_help` MCP tool). ChatPanel reads
+ * pending rows on open, prepends them as a user turn, and marks
+ * them consumed so the next open doesn't re-replay them.
+ */
+export const helpRequests = pgTable(
+  "help_requests",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    learnerId: uuid("learner_id")
+      .notNull()
+      .references(() => learners.id, { onDelete: "cascade" }),
+    tutorialSlug: text("tutorial_slug").notNull(),
+    stepSlug: text("step_slug").notNull(),
+    query: text("query").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    consumedAt: timestamp("consumed_at", { withTimezone: true }),
+  },
+  (table) => ({
+    byLearnerPending: index("help_requests_by_learner_pending").on(
+      table.learnerId,
+      table.consumedAt,
+    ),
+  }),
+);
+
 export const progressEntries = pgTable(
   "progress_entries",
   {