pi-learning-agent 0.1.0

package/extension/transcript-sync.ts

@@ -0,0 +1,197 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** Subset of LearningServer used by transcript sync (spec 26). */
+export interface TranscriptSyncServer {
+  broadcastTutorMessage(
+    role: "assistant",
+    text: string,
+    messageId: string | undefined,
+    done: boolean
+  ): void;
+  broadcastTutorStatus(status: "waiting" | "idle", toolName?: string): void;
+}
+
+/** Injectable scheduler/clock for throttling tests. */
+export interface TranscriptSyncOptions {
+  throttleMs?: number;
+  /** Opaque timer handle (number in browsers/tests, NodeJS.Timeout in Node). */
+  setTimeoutFn?: (fn: () => void, ms: number) => unknown;
+  clearTimeoutFn?: (handle: unknown) => void;
+}
+
+/**
+ * Extract the learner-visible assistant text from a message (spec 26).
+ * Only role === "assistant" messages qualify; string content is used as-is,
+ * array content is concatenated from `text` parts only (images and other
+ * parts are skipped). Returns undefined for non-assistant or non-text
+ * content. Reasoning/thinking is never part of the visible text.
+ */
+export function extractAssistantText(message: {
+  role?: string;
+  content?: unknown;
+}): string | undefined {
+  if (message.role !== "assistant") {
+    return undefined;
+  }
+  const { content } = message;
+  if (typeof content === "string") {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return undefined;
+  }
+  const text = content
+    .filter(
+      (part): part is { type: "text"; text: string } =>
+        typeof part === "object" &&
+        part !== null &&
+        (part as { type?: unknown }).type === "text" &&
+        typeof (part as { text?: unknown }).text === "string"
+    )
+    .map((part) => part.text)
+    .join("");
+  return text;
+}
+
+/**
+ * Key a pi message for streaming correlation. AgentMessage has no id field;
+ * AssistantMessage.responseId is the provider response id, stable across all
+ * message_update/message_end frames of one streamed response. When absent,
+ * fall back to the current streaming key (set by message_update) or a local
+ * per-sync sequence — Pi delivers one message's events sequentially, so the
+ * end frame always follows the updates of the same message.
+ */
+function messageKey(responseId: unknown, current: string | undefined): string {
+  if (typeof responseId === "string" && responseId !== "") {
+    return responseId;
+  }
+  return current ?? "";
+}
+
+/**
+ * Sync the tutor's visible transcript to web clients (spec 26): streamed
+ * assistant text on message_update (throttled), final text on message_end,
+ * learning-tool waiting status, and idle signals.
+ *
+ * Ordering guarantee: the done:true frame for a messageId is always last.
+ * On message_end any throttled-but-unflushed partial frame for that message
+ * is dropped (the final frame carries the complete text, so the client
+ * converges to the same content — simpler than force-flushing).
+ */
+export function registerTranscriptSync(
+  pi: ExtensionAPI,
+  server: TranscriptSyncServer,
+  options: TranscriptSyncOptions = {}
+): void {
+  const throttleMs = options.throttleMs ?? 100;
+  const schedule: (fn: () => void, ms: number) => unknown =
+    options.setTimeoutFn ?? ((fn, ms) => setTimeout(fn, ms));
+  const cancel: (handle: unknown) => void =
+    options.clearTimeoutFn ?? ((handle) => clearTimeout(handle as NodeJS.Timeout));
+
+  // ponytail: single in-flight streaming message tracked; Pi streams one
+  // message at a time, per-message trackers only if concurrency appears.
+  let currentKey: string | undefined;
+  let pendingText: string | undefined;
+  let pendingKey: string | undefined;
+  let timer: unknown;
+  let seq = 0;
+  const attemptMisconceptions = new Map<string, string>();
+
+  function flush(): void {
+    timer = undefined;
+    if (pendingKey !== undefined && pendingText !== undefined) {
+      server.broadcastTutorMessage("assistant", pendingText, pendingKey, false);
+    }
+    pendingKey = undefined;
+    pendingText = undefined;
+  }
+
+  pi.on("message_update", (event) => {
+    const text = extractAssistantText(event.message);
+    if (text === undefined || text.trim() === "") {
+      return;
+    }
+    let key = messageKey(
+      (event.message as { responseId?: unknown }).responseId,
+      currentKey
+    );
+    if (key === "") {
+      key = `msg-${++seq}`;
+    }
+    currentKey = key;
+    // 节流窗口内只保留最新文本，flush 时广播一帧。
+    pendingKey = key;
+    pendingText = text;
+    if (timer === undefined) {
+      timer = schedule(flush, throttleMs);
+    }
+  });
+
+  pi.on("message_end", (event) => {
+    const text = extractAssistantText(event.message);
+    if (text === undefined || text.trim() === "") {
+      // 无可见文本：丢弃未 flush 的流式帧（终帧也不发）。
+      if (timer !== undefined) {
+        cancel(timer);
+        timer = undefined;
+      }
+      pendingKey = undefined;
+      pendingText = undefined;
+      currentKey = undefined;
+      return;
+    }
+    const key = messageKey(
+      (event.message as { responseId?: unknown }).responseId,
+      currentKey
+    );
+    const messageId = key === "" ? `msg-${++seq}` : key;
+    // 终帧携带完整文本：取消未 flush 的节流帧，保证 done:true 最后到达。
+    if (timer !== undefined) {
+      cancel(timer);
+      timer = undefined;
+    }
+    pendingKey = undefined;
+    pendingText = undefined;
+    currentKey = undefined;
+    server.broadcastTutorMessage("assistant", text, messageId, true);
+  });
+
+  pi.on("tool_execution_start", (event) => {
+    if (event.toolName === "learning_record_attempt") {
+      // 结束事件没有 args，先保留本次评分提供的误区说明。
+      const misconception = event.args?.misconception;
+      if (typeof misconception === "string" && misconception.trim() !== "") {
+        attemptMisconceptions.set(event.toolCallId, misconception);
+      }
+    }
+    if (event.toolName.startsWith("learning_ask_")) {
+      server.broadcastTutorStatus("waiting", event.toolName);
+    }
+  });
+
+  pi.on("tool_execution_end", (event) => {
+    const misconception = attemptMisconceptions.get(event.toolCallId);
+    attemptMisconceptions.delete(event.toolCallId);
+    if (event.toolName === "learning_record_attempt" && !event.isError) {
+      // 只展示成功结果中的判定，不能将开始评分等同于评分成功。
+      const outcome = event.result?.details?.outcome;
+      const verdict = outcome === "correct" ? "回答正确"
+        : outcome === "partial" ? "回答部分正确"
+        : outcome === "incorrect" ? "回答不正确" : undefined;
+      if (verdict !== undefined) {
+        const explanation = event.result?.details?.explanation;
+        const feedback = typeof explanation === "string" && explanation.trim() !== ""
+          ? explanation
+          : misconception === undefined ? "" : `需要纠正的理解：${misconception}`;
+        const text = `**${verdict}**` + (feedback === "" ? "" : `\n\n${feedback}`);
+        server.broadcastTutorMessage("assistant", text, `attempt-${event.toolCallId}`, true);
+      }
+    }
+  });
+
+  pi.on("agent_settled", () => {
+    attemptMisconceptions.clear();
+    server.broadcastTutorStatus("idle");
+  });
+}

package/extension/tutor-prompt.ts

@@ -0,0 +1,64 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { LearningStateStore } from "./state/learning-state.js";
+
+export interface TutorPromptDependencies {
+  state: LearningStateStore;
+}
+
+export function registerTutorPrompt(
+  pi: ExtensionAPI,
+  dependencies: TutorPromptDependencies
+): void {
+  pi.on("before_agent_start", (event) => {
+    const state = dependencies.state.snapshot();
+    if (!state.enabled) {
+      return;
+    }
+
+    const conceptState = Object.values(state.concepts).map((concept) => {
+      const misconceptions = concept.misconceptions
+        .slice(0, 3)
+        .map(toPromptLine)
+        .join(" | ");
+      return (
+        `- ${toPromptLine(concept.id)}: mastery=${concept.mastery.toFixed(2)}, ` +
+        `attempts=${concept.attempts}, correct=${concept.correct}, ` +
+        `misconceptions=${misconceptions === "" ? "none" : misconceptions}`
+      );
+    });
+
+    const learningPrompt = [
+      "You are operating in Learning Mode.",
+      "",
+      "Teaching rules:",
+      "1. Teach interactively rather than dumping a full solution.",
+      "2. Use one primary learner interaction at a time.",
+      "3. Use learning_ask_single_choice for single-choice checks; do not render fake choices in Markdown.",
+      "4. Use learning_ask_multi_choice when multiple answers are correct; do not render fake checkboxes in Markdown.",
+      "5. Use learning_ask_free_response for open learner responses.",
+      "6. Use learning_ask_code for coding exercises; do not ask the learner to paste code into ordinary chat.",
+      "7. After an answer, evaluate it, explain the key point, and decide the next teaching action.",
+      "8. Prefer retrieval practice and application over repeated explanation.",
+      "9. Adapt difficulty to the learner state and do not infer mastery from one lucky choice.",
+      "10. Keep explanations concise enough to preserve active participation.",
+      "11. When a registered learning interaction tool fits, use it instead of ordinary chat input.",
+      "12. Make every learning_ask_* prompt self-contained: put all code, examples, and context inside the question/instructions parameter itself. The learner's active panel shows only that parameter's content, never your previous chat messages — a question without its code is unanswerable.",
+      "13. After evaluating each answer, call learning_record_attempt with that interaction's interactionId, the conceptId, outcome (correct/partial/incorrect), evidenceType matching the interaction (choice for single/multi choice, free_response for open answers, code for code exercises), and a required explanation of the correct answer and key reasoning in the learner's language. The workspace displays this explanation with the outcome; complete this feedback before asking the next question. Include misconception when the answer was wrong. Do not record attempts whose tool result says skipped: true — a skipped question is not an answer.",
+      "",
+      `Current course: ${state.course?.title ?? "unspecified"}`,
+      `Current topic: ${state.topic?.title ?? "unspecified"}`,
+      `Current phase: ${state.phase}`,
+      `Tracked concepts: ${Object.keys(state.concepts).length}`,
+      `Recent attempts: ${state.recentAttempts.length}`,
+      "Concept state:",
+      ...(conceptState.length === 0 ? ["- none"] : conceptState)
+    ].join("\n");
+
+    return { systemPrompt: `${event.systemPrompt}\n\n${learningPrompt}` };
+  });
+}
+
+function toPromptLine(value: string): string {
+  return value.replace(/\s+/gu, " ").trim().slice(0, 200);
+}

package/extension/utils/browser.ts

@@ -0,0 +1,35 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Open a URL in the system browser (spec 19). Never rejects: the caller has
+ * already shown the URL, so a missing opener must not break the command.
+ * Uses spawn (no shell string interpolation) to avoid quoting issues.
+ *
+ * Headless/CI (spec 19): set PI_LEARNING_NO_BROWSER=1 to skip the opener
+ * entirely. The workspace URL is still printed by /learn, so an automated or
+ * remote run loses nothing.
+ */
+export function openWorkspace(url: string): Promise<void> {
+  if (process.env.PI_LEARNING_NO_BROWSER === "1") {
+    return Promise.resolve();
+  }
+
+  let command: string;
+  let args: string[];
+  if (process.platform === "win32") {
+    command = "cmd.exe";
+    args = ["/c", "start", "", url];
+  } else if (process.platform === "darwin") {
+    command = "open";
+    args = [url];
+  } else {
+    command = "xdg-open";
+    args = [url];
+  }
+
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: "ignore", windowsHide: true });
+    child.once("error", () => resolve());
+    child.once("exit", () => resolve());
+  });
+}

package/extension/utils/ids.ts

@@ -0,0 +1,5 @@
+import { randomUUID } from "node:crypto";
+
+export function createInteractionId(prefix: string): string {
+  return `${prefix}_${randomUUID()}`;
+}

package/extension/utils/validation.ts

@@ -0,0 +1,138 @@
+import type {
+  CodeExerciseAnswer,
+  FreeResponseAnswer,
+  LearningInteraction,
+  MultiChoiceAnswer,
+  SingleChoiceAnswer
+} from "../../shared/protocol.js";
+
+export type AnswerValidationResult =
+  | { ok: true; type: "single_choice"; answer: SingleChoiceAnswer }
+  | { ok: true; type: "multi_choice"; answer: MultiChoiceAnswer }
+  | { ok: true; type: "free_response"; answer: FreeResponseAnswer }
+  | { ok: true; type: "code"; answer: CodeExerciseAnswer }
+  | { ok: false; message: string };
+
+export function validateInteractionAnswer(
+  interaction: LearningInteraction,
+  answer: unknown
+): AnswerValidationResult {
+  if (interaction.type === "code") {
+    if (
+      typeof answer !== "object" ||
+      answer === null ||
+      !("language" in answer) ||
+      typeof answer.language !== "string" ||
+      !("code" in answer) ||
+      typeof answer.code !== "string"
+    ) {
+      return {
+        ok: false,
+        message: `Interaction ${interaction.id} requires language and code strings.`
+      };
+    }
+    if (answer.language !== interaction.language) {
+      return {
+        ok: false,
+        message: `Language ${answer.language} does not match interaction ${interaction.id}.`
+      };
+    }
+
+    return {
+      ok: true,
+      type: interaction.type,
+      answer: { language: answer.language, code: answer.code }
+    };
+  }
+
+  if (interaction.type === "free_response") {
+    if (
+      typeof answer !== "object" ||
+      answer === null ||
+      !("text" in answer) ||
+      typeof answer.text !== "string"
+    ) {
+      return {
+        ok: false,
+        message: `Interaction ${interaction.id} requires a text string.`
+      };
+    }
+
+    return { ok: true, type: interaction.type, answer: { text: answer.text } };
+  }
+
+  if (interaction.type === "multi_choice") {
+    if (
+      typeof answer !== "object" ||
+      answer === null ||
+      !("optionIds" in answer) ||
+      !Array.isArray(answer.optionIds)
+    ) {
+      return {
+        ok: false,
+        message: `Interaction ${interaction.id} requires an optionIds array.`
+      };
+    }
+
+    if (answer.optionIds.length === 0) {
+      return {
+        ok: false,
+        message: `Interaction ${interaction.id} requires at least one selected option.`
+      };
+    }
+
+    if (!answer.optionIds.every((optionId) => typeof optionId === "string")) {
+      return {
+        ok: false,
+        message: `Interaction ${interaction.id} requires optionIds to be strings.`
+      };
+    }
+
+    const validIds = new Set(interaction.options.map((option) => option.id));
+    const unknown = answer.optionIds.find((optionId) => !validIds.has(optionId));
+    if (unknown !== undefined) {
+      return {
+        ok: false,
+        message: `Option ${unknown} does not belong to interaction ${interaction.id}.`
+      };
+    }
+
+    if (new Set(answer.optionIds).size !== answer.optionIds.length) {
+      return {
+        ok: false,
+        message: `Interaction ${interaction.id} contains duplicate options.`
+      };
+    }
+
+    return {
+      ok: true,
+      type: interaction.type,
+      answer: { optionIds: answer.optionIds }
+    };
+  }
+
+  if (
+    typeof answer !== "object" ||
+    answer === null ||
+    !("optionId" in answer) ||
+    typeof answer.optionId !== "string"
+  ) {
+    return {
+      ok: false,
+      message: `Interaction ${interaction.id} requires an optionId string.`
+    };
+  }
+
+  if (!interaction.options.some((option) => option.id === answer.optionId)) {
+    return {
+      ok: false,
+      message: `Option ${answer.optionId} does not belong to interaction ${interaction.id}.`
+    };
+  }
+
+  return {
+    ok: true,
+    type: interaction.type,
+    answer: { optionId: answer.optionId }
+  };
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "pi-learning-agent",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Structured learning interactions for Pi Coding Agent",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "learning",
+    "tutor"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marskim1130/pi-learning.git"
+  },
+  "homepage": "https://github.com/marskim1130/pi-learning#readme",
+  "bugs": {
+    "url": "https://github.com/marskim1130/pi-learning/issues"
+  },
+  "files": [
+    "extension/",
+    "shared/",
+    "web/dist/",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "docs/architecture.md",
+    "docs/images/learning-workspace.png",
+    "docs/releasing.md"
+  ],
+  "workspaces": [
+    "web"
+  ],
+  "pi": {
+    "extensions": [
+      "./extension/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "typecheck:web": "npm --prefix web run typecheck",
+    "build:web": "npm --prefix web run build",
+    "check": "npm run typecheck && npm run typecheck:web && npm test",
+    "e2e": "node tests/e2e-rpc.mjs",
+    "e2e:browser": "playwright test",
+    "test:workspace": "playwright test --config playwright.workspace.config.ts",
+    "pi": "pi -e ./extension/index.ts",
+    "check:package": "npm run build:web && vitest run --config vitest.release.config.ts",
+    "smoke": "node tests/rpc-smoke.mjs",
+    "check:release": "npm run check && npm run check:package && npm run smoke",
+    "release:prepare": "npm run check:release && npm pack --ignore-scripts",
+    "prepack": "npm run build:web"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "overrides": {
+    "monaco-editor@0.56.0": {
+      "dompurify": "3.4.13"
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.0",
+    "@earendil-works/pi-coding-agent": "0.84.0",
+    "@playwright/test": "^1.62.1",
+    "@types/node": "24.12.4",
+    "jsdom": "^30.0.1",
+    "typebox": "1.3.7",
+    "typescript": "5.9.3",
+    "vitest": "4.1.9"
+  }
+}

package/shared/learning-state.ts

@@ -0,0 +1,62 @@
+export type LearningPhase =
+  | "idle"
+  | "diagnosing"
+  | "explaining"
+  | "checking"
+  | "practicing"
+  | "reviewing";
+
+export interface LearningCourse {
+  id: string;
+  title: string;
+}
+
+export interface LearningTopic {
+  id: string;
+  title: string;
+}
+
+export type AttemptOutcome = "correct" | "partial" | "incorrect";
+
+export type EvidenceType = "choice" | "free_response" | "code";
+
+/** One recorded answer, newest first; drives the 0.75 ceiling rule (spec 16.1). */
+export interface RecentOutcome {
+  outcome: AttemptOutcome;
+  evidenceType: EvidenceType;
+}
+
+export interface ConceptState {
+  id: string;
+  title: string;
+  mastery: number;
+  attempts: number;
+  correct: number;
+  lastPracticedAt?: number;
+  misconceptions: string[];
+  /**
+   * Optional: absent in snapshots written before this field existed, so
+   * restore() must keep accepting concepts without it (backward compatible).
+   */
+  recentOutcomes?: RecentOutcome[];
+}
+
+export interface AttemptSummary {
+  interactionId: string;
+  conceptId: string;
+  outcome: AttemptOutcome;
+  evidenceType: EvidenceType;
+  misconception?: string;
+  recordedAt: number;
+}
+
+export interface LearningState {
+  enabled: boolean;
+  course?: LearningCourse;
+  topic?: LearningTopic;
+  phase: LearningPhase;
+  concepts: Record<string, ConceptState>;
+  recentAttempts: AttemptSummary[];
+  /** Bounded idempotency ledger; optional for snapshots written before v0.1. */
+  recordedInteractionIds?: string[];
+}