handzon-core 0.7.0 → 0.8.1

package/src/server/mcp/writeTools.ts

@@ -0,0 +1,407 @@
+import { getStep } from "../../lib/content.ts";
+import { getDb } from "../db/client.ts";
+import { helpRequests } from "../db/schema.ts";
+import { writeProgressEntries } from "../progress.ts";
+import { type CheckObservation, evaluate } from "../verify/evaluator.ts";
+import { errorResult, type McpTool, text } from "./protocol.ts";
+
+const SCOPE = "progress:write";
+
+function requireLearner(learnerId: string | undefined) {
+  if (!learnerId) {
+    throw new Error("No resolved learner — bearer token required.");
+  }
+  return learnerId;
+}
+
+/**
+ * MCP write tools. Each one builds the same `{ kind, scope, key, value }`
+ * row shape the cookie-authed /api/progress endpoint accepts and pipes
+ * it through the shared writeProgressEntries() writer. Sources tag the
+ * row with `source: "mcp"` so author-side telemetry can distinguish
+ * agent-driven completions from in-browser clicks.
+ */
+export const progressWriteTools: McpTool[] = [
+  {
+    name: "complete_checkpoint",
+    description:
+      "Mark a checkpoint complete for the authenticated learner. Optionally include evidence (command, output, files) for telemetry.",
+    requiredScope: SCOPE,
+    inputSchema: {
+      type: "object",
+      properties: {
+        tutorial: { type: "string", minLength: 1 },
+        step: { type: "string", minLength: 1 },
+        checkpointId: { type: "string", minLength: 1 },
+        evidence: {
+          type: "object",
+          properties: {
+            command: { type: "string" },
+            output: { type: "string" },
+            files: { type: "object" },
+          },
+          additionalProperties: true,
+        },
+      },
+      required: ["tutorial", "step", "checkpointId"],
+      additionalProperties: false,
+    },
+    handler: async (args, ctx) => {
+      const a = args as {
+        tutorial: string;
+        step: string;
+        checkpointId: string;
+        evidence?: Record<string, unknown>;
+      };
+      const learnerId = requireLearner(ctx.learnerId);
+      // Checkpoint rows use scope "global" to match the in-browser
+      // client (state.checkpoints is keyed by checkpoint id, not
+      // by step). Tutorial + step are part of the value payload
+      // for telemetry and for the SSE handler that wants to know
+      // which step the ack belongs to.
+      await writeProgressEntries(learnerId, [
+        {
+          kind: "checkpoint",
+          scope: "global",
+          key: a.checkpointId,
+          value: {
+            source: "mcp",
+            tutorial: a.tutorial,
+            step: a.step,
+            evidence: a.evidence ?? null,
+            ts: Date.now(),
+          },
+        },
+      ]);
+      return text(`Checkpoint ${a.checkpointId} marked complete.`);
+    },
+  },
+  {
+    name: "uncheck_checkpoint",
+    description: "Undo a previously completed checkpoint (tombstone the row).",
+    requiredScope: SCOPE,
+    inputSchema: {
+      type: "object",
+      properties: {
+        tutorial: { type: "string", minLength: 1 },
+        step: { type: "string", minLength: 1 },
+        checkpointId: { type: "string", minLength: 1 },
+      },
+      required: ["tutorial", "step", "checkpointId"],
+      additionalProperties: false,
+    },
+    handler: async (args, ctx) => {
+      const a = args as { tutorial: string; step: string; checkpointId: string };
+      const learnerId = requireLearner(ctx.learnerId);
+      // Uncheck also drops the matching kind:"verification" telemetry
+      // row so a re-attempt isn't pre-poisoned by the previous
+      // failure feedback.
+      await writeProgressEntries(learnerId, [
+        { kind: "checkpoint", scope: "global", key: a.checkpointId, value: null },
+        {
+          kind: "verification",
+          scope: `${a.tutorial}/${a.step}`,
+          key: a.checkpointId,
+          value: null,
+        },
+      ]);
+      return text(`Checkpoint ${a.checkpointId} unchecked.`);
+    },
+  },
+  {
+    name: "complete_step",
+    description: "Mark a step complete (mirrors clicking through after a checkpoint).",
+    requiredScope: SCOPE,
+    inputSchema: {
+      type: "object",
+      properties: {
+        tutorial: { type: "string", minLength: 1 },
+        step: { type: "string", minLength: 1 },
+      },
+      required: ["tutorial", "step"],
+      additionalProperties: false,
+    },
+    handler: async (args, ctx) => {
+      const a = args as { tutorial: string; step: string };
+      const learnerId = requireLearner(ctx.learnerId);
+      await writeProgressEntries(learnerId, [
+        {
+          kind: "step",
+          scope: a.tutorial,
+          key: a.step,
+          value: "complete",
+        },
+      ]);
+      return text(`Step ${a.step} marked complete.`);
+    },
+  },
+  {
+    name: "mark_step_incomplete",
+    description: "Undo a step completion.",
+    requiredScope: SCOPE,
+    inputSchema: {
+      type: "object",
+      properties: {
+        tutorial: { type: "string", minLength: 1 },
+        step: { type: "string", minLength: 1 },
+      },
+      required: ["tutorial", "step"],
+      additionalProperties: false,
+    },
+    handler: async (args, ctx) => {
+      const a = args as { tutorial: string; step: string };
+      const learnerId = requireLearner(ctx.learnerId);
+      await writeProgressEntries(learnerId, [
+        {
+          kind: "step",
+          scope: a.tutorial,
+          key: a.step,
+          value: null,
+        },
+      ]);
+      return text(`Step ${a.step} marked incomplete.`);
+    },
+  },
+  {
+    name: "record_quiz",
+    description: "Record a quiz attempt (chosen indices + correct flag).",
+    requiredScope: SCOPE,
+    inputSchema: {
+      type: "object",
+      properties: {
+        tutorial: { type: "string", minLength: 1 },
+        quizId: { type: "string", minLength: 1 },
+        chosen: { type: "array", items: { type: "integer" } },
+        correct: { type: "boolean" },
+      },
+      required: ["tutorial", "quizId", "chosen", "correct"],
+      additionalProperties: false,
+    },
+    handler: async (args, ctx) => {
+      const a = args as {
+        tutorial: string;
+        quizId: string;
+        chosen: number[];
+        correct: boolean;
+      };
+      const learnerId = requireLearner(ctx.learnerId);
+      await writeProgressEntries(learnerId, [
+        {
+          kind: "quiz",
+          scope: a.tutorial,
+          key: a.quizId,
+          value: { chosen: a.chosen, correct: a.correct, ts: Date.now(), source: "mcp" },
+        },
+      ]);
+      return text(`Quiz ${a.quizId} recorded.`);
+    },
+  },
+  {
+    name: "set_last_visited",
+    description: "Update the learner's last-visited step for a tutorial.",
+    requiredScope: SCOPE,
+    inputSchema: {
+      type: "object",
+      properties: {
+        tutorial: { type: "string", minLength: 1 },
+        step: { type: "string", minLength: 1 },
+      },
+      required: ["tutorial", "step"],
+      additionalProperties: false,
+    },
+    handler: async (args, ctx) => {
+      const a = args as { tutorial: string; step: string };
+      const learnerId = requireLearner(ctx.learnerId);
+      await writeProgressEntries(learnerId, [
+        {
+          kind: "lastVisited",
+          scope: a.tutorial,
+          key: "step",
+          value: { step: a.step, ts: Date.now() },
+        },
+      ]);
+      return text(`Last-visited set to ${a.tutorial}/${a.step}.`);
+    },
+  },
+  {
+    name: "request_help",
+    description:
+      "Post a help request from the agent into the in-browser tutor's inbox. The next time the learner opens ChatPanel, your query is prepended as a user turn.",
+    requiredScope: SCOPE,
+    inputSchema: {
+      type: "object",
+      properties: {
+        tutorial: { type: "string", minLength: 1 },
+        step: { type: "string", minLength: 1 },
+        query: { type: "string", minLength: 1 },
+      },
+      required: ["tutorial", "step", "query"],
+      additionalProperties: false,
+    },
+    handler: async (args, ctx) => {
+      const a = args as { tutorial: string; step: string; query: string };
+      const learnerId = requireLearner(ctx.learnerId);
+      const db = getDb();
+      const [row] = await db
+        .insert(helpRequests)
+        .values({
+          learnerId,
+          tutorialSlug: a.tutorial,
+          stepSlug: a.step,
+          query: a.query,
+        })
+        .returning({ id: helpRequests.id });
+      return text(
+        `Help request queued (${row!.id}). It will appear in the learner's tutor on next open.`,
+      );
+    },
+  },
+  {
+    name: "set_preference",
+    description: "Set a learner preference (free-form key/value).",
+    requiredScope: SCOPE,
+    inputSchema: {
+      type: "object",
+      properties: {
+        key: { type: "string", minLength: 1 },
+        value: {},
+      },
+      required: ["key", "value"],
+      additionalProperties: false,
+    },
+    handler: async (args, ctx) => {
+      const a = args as { key: string; value: unknown };
+      const learnerId = requireLearner(ctx.learnerId);
+      await writeProgressEntries(learnerId, [
+        {
+          kind: "pref",
+          scope: "global",
+          key: a.key,
+          value: a.value,
+        },
+      ]);
+      return text(`Preference ${a.key} set.`);
+    },
+  },
+];
+
+/**
+ * Catch-all helper for surfacing handler errors as MCP-shaped error
+ * results — keeps the tool factories tidy when a wrapped call fails.
+ */
+export function toolError(message: string) {
+  return errorResult(message);
+}
+
+/**
+ * Family D verification: agent reports observations, server scores.
+ * On pass, the same writeProgressEntries() path that
+ * complete_checkpoint uses fires + a kind:"verification" telemetry
+ * row lands. On fail, only the telemetry row lands and the verdict
+ * is returned to the agent. SSE fans the telemetry row to the open
+ * browser tab so <Checkpoint> can render an inline failure hint.
+ */
+export const verificationTools: McpTool[] = [
+  {
+    name: "submit_verification",
+    description:
+      "Submit observed values for the current step's verify checks. The server scores against the declared spec and (on pass) marks the matching checkpoint complete. On fail, returns the failing check + hint and does not write a checkpoint row.",
+    requiredScope: SCOPE,
+    inputSchema: {
+      type: "object",
+      properties: {
+        tutorial: { type: "string", minLength: 1 },
+        step: { type: "string", minLength: 1 },
+        observations: {
+          type: "array",
+          description:
+            "One observation per declared check, in order. Fields per kind: file_exists {exists}, file_contains {exists, body}, shell {exitCode, stdout}, http {status, responseBody}.",
+          items: { type: "object" },
+        },
+      },
+      required: ["tutorial", "step", "observations"],
+      additionalProperties: false,
+    },
+    handler: async (args, ctx) => {
+      const a = args as {
+        tutorial: string;
+        step: string;
+        observations: CheckObservation[];
+      };
+      const learnerId = requireLearner(ctx.learnerId);
+      const stepEntry = await getStep(a.tutorial, a.step);
+      if (!stepEntry) {
+        return errorResult(`No step "${a.step}" in "${a.tutorial}".`);
+      }
+      const spec = (stepEntry.data as { verify?: unknown }).verify as
+        | import("../../collections.ts").VerifySpec
+        | undefined;
+      if (!spec) {
+        return errorResult(
+          `Step ${a.tutorial}/${a.step} has no verify block. Use complete_checkpoint for prose-fallback verification.`,
+        );
+      }
+
+      const verdict = evaluate(spec, a.observations);
+      const scope = `${a.tutorial}/${a.step}`;
+      const ts = Date.now();
+
+      if (verdict.passed) {
+        await writeProgressEntries(learnerId, [
+          {
+            kind: "checkpoint",
+            scope: "global",
+            key: spec.id,
+            value: {
+              source: "verify",
+              tutorial: a.tutorial,
+              step: a.step,
+              results: a.observations,
+              ts,
+            },
+          },
+          {
+            kind: "verification",
+            scope,
+            key: spec.id,
+            value: { pass: true, ts },
+          },
+        ]);
+        return text(
+          JSON.stringify(
+            { passed: true, checkpointId: spec.id, message: "All checks passed." },
+            null,
+            2,
+          ),
+        );
+      }
+
+      await writeProgressEntries(learnerId, [
+        {
+          kind: "verification",
+          scope,
+          key: spec.id,
+          value: {
+            pass: false,
+            failingCheckIndex: verdict.failingCheckIndex,
+            reason: verdict.reason,
+            hint: verdict.hint,
+            ts,
+          },
+        },
+      ]);
+      return text(
+        JSON.stringify(
+          {
+            passed: false,
+            failingCheckIndex: verdict.failingCheckIndex,
+            reason: verdict.reason,
+            hint: verdict.hint,
+          },
+          null,
+          2,
+        ),
+      );
+    },
+  },
+];

package/src/server/progress.ts

@@ -0,0 +1,86 @@
+import { and, eq, sql } from "drizzle-orm";
+import { getDb } from "./db/client.ts";
+import { progressEntries } from "./db/schema.ts";
+import { publishLearner } from "./progressBus.ts";
+
+export type ProgressKind =
+  | "step"
+  | "checkpoint"
+  | "quiz"
+  | "pref"
+  | "lastVisited"
+  | "tutorial"
+  | "verification";
+
+export interface ProgressEntryWrite {
+  kind: ProgressKind;
+  scope: string;
+  key: string;
+  /** Use `null` to delete the row (the tombstone signal). */
+  value: unknown;
+}
+
+/**
+ * Shared writer used by both the cookie-authed POST /api/progress
+ * handler and the bearer-authed MCP write tools. Splits entries into
+ * deletes (value === null) and upserts, then runs them with the same
+ * UPSERT semantics the API handler uses.
+ *
+ * Returns the count of rows written/deleted so the caller can echo a
+ * sensible response back.
+ */
+export async function writeProgressEntries(
+  learnerId: string,
+  entries: ProgressEntryWrite[],
+): Promise<number> {
+  if (entries.length === 0) return 0;
+  const db = getDb();
+  const now = new Date();
+  const deletes = entries.filter((e) => e.value === null);
+  const upserts = entries.filter((e) => e.value !== null);
+
+  for (const d of deletes) {
+    await db
+      .delete(progressEntries)
+      .where(
+        and(
+          eq(progressEntries.learnerId, learnerId),
+          eq(progressEntries.kind, d.kind),
+          eq(progressEntries.scope, d.scope),
+          eq(progressEntries.key, d.key),
+        ),
+      );
+  }
+
+  if (upserts.length > 0) {
+    const rows = upserts.map((b) => ({
+      learnerId,
+      kind: b.kind,
+      scope: b.scope,
+      key: b.key,
+      value: b.value,
+      updatedAt: now,
+    }));
+    await db
+      .insert(progressEntries)
+      .values(rows)
+      .onConflictDoUpdate({
+        target: [
+          progressEntries.learnerId,
+          progressEntries.kind,
+          progressEntries.scope,
+          progressEntries.key,
+        ],
+        set: {
+          value: sql`excluded.value`,
+          updatedAt: sql`excluded.updated_at`,
+        },
+      });
+  }
+
+  // Fan out to any open SSE subscriber for this learner so the
+  // browser tab catches MCP-driven writes without a polling loop.
+  publishLearner(learnerId, entries);
+
+  return entries.length;
+}

package/src/server/progressBus.ts

@@ -0,0 +1,51 @@
+import type { ProgressEntryWrite } from "./progress.ts";
+
+/**
+ * Process-local pub/sub for progress writes. Both the cookie-authed
+ * POST /api/progress handler and the MCP write tools call publish()
+ * after persisting; the SSE endpoint subscribes per learner so the
+ * open browser tab sees MCP-driven writes within one event-loop
+ * tick.
+ *
+ * Multi-instance caveat: on a horizontally-scaled deploy, a write
+ * landing on instance A is invisible to a subscriber on instance B.
+ * v1 is single-instance; v2 swaps this for Postgres LISTEN/NOTIFY on
+ * a "learner_<uuid>" channel (Postgres is already in the stack).
+ */
+
+export interface ProgressBusMessage extends ProgressEntryWrite {
+  ts: number;
+}
+
+type Listener = (msg: ProgressBusMessage) => void;
+
+const channels = new Map<string, Set<Listener>>();
+
+export function subscribeLearner(learnerId: string, listener: Listener): () => void {
+  let set = channels.get(learnerId);
+  if (!set) {
+    set = new Set();
+    channels.set(learnerId, set);
+  }
+  set.add(listener);
+  return () => {
+    set?.delete(listener);
+    if (set && set.size === 0) channels.delete(learnerId);
+  };
+}
+
+export function publishLearner(learnerId: string, entries: ProgressEntryWrite[]): void {
+  const subs = channels.get(learnerId);
+  if (!subs || subs.size === 0) return;
+  const ts = Date.now();
+  for (const entry of entries) {
+    const msg: ProgressBusMessage = { ...entry, ts };
+    for (const fn of subs) {
+      try {
+        fn(msg);
+      } catch (e) {
+        console.warn("[handzon] progress bus listener threw:", e);
+      }
+    }
+  }
+}

package/src/server/tokens.ts

@@ -0,0 +1,80 @@
+import { and, desc, eq } from "drizzle-orm";
+import { generatePat, hashPat } from "./auth.ts";
+import { getDb } from "./db/client.ts";
+import { learnerApiTokens } from "./db/schema.ts";
+
+/** Known scopes. The MCP endpoint gates writes on progress:write;
+ * catalog reads need any valid token. We keep the strings as
+ * comma-joined values in DB to mirror what an OAuth 2.1 token would
+ * carry in the v2 proxy.
+ */
+export const KNOWN_SCOPES = ["progress:read", "progress:write"] as const;
+export type Scope = (typeof KNOWN_SCOPES)[number];
+
+export interface TokenRow {
+  id: string;
+  name: string;
+  scopes: string[];
+  createdAt: Date;
+  lastUsedAt: Date | null;
+  expiresAt: Date | null;
+}
+
+export async function listTokens(userId: string): Promise<TokenRow[]> {
+  const db = getDb();
+  const rows = await db
+    .select({
+      id: learnerApiTokens.id,
+      name: learnerApiTokens.name,
+      scopes: learnerApiTokens.scopes,
+      createdAt: learnerApiTokens.createdAt,
+      lastUsedAt: learnerApiTokens.lastUsedAt,
+      expiresAt: learnerApiTokens.expiresAt,
+    })
+    .from(learnerApiTokens)
+    .where(eq(learnerApiTokens.userId, userId))
+    .orderBy(desc(learnerApiTokens.createdAt));
+  return rows.map((r) => ({
+    ...r,
+    scopes: r.scopes
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  }));
+}
+
+/**
+ * Mint a new PAT for the user. Returns the raw token *once* — it is
+ * never stored, and there is no path to recover it. Caller is
+ * responsible for showing it to the user a single time.
+ */
+export async function createToken(opts: {
+  userId: string;
+  name: string;
+  scopes: Scope[];
+  expiresAt?: Date | null;
+}): Promise<{ id: string; raw: string }> {
+  const db = getDb();
+  const raw = generatePat();
+  const tokenHash = await hashPat(raw);
+  const [row] = await db
+    .insert(learnerApiTokens)
+    .values({
+      userId: opts.userId,
+      name: opts.name,
+      tokenHash,
+      scopes: opts.scopes.join(","),
+      expiresAt: opts.expiresAt ?? null,
+    })
+    .returning({ id: learnerApiTokens.id });
+  return { id: row!.id, raw };
+}
+
+export async function revokeToken(userId: string, tokenId: string): Promise<boolean> {
+  const db = getDb();
+  const result = await db
+    .delete(learnerApiTokens)
+    .where(and(eq(learnerApiTokens.userId, userId), eq(learnerApiTokens.id, tokenId)))
+    .returning({ id: learnerApiTokens.id });
+  return result.length > 0;
+}