pi-learning-agent 0.1.0

package/extension/learning-session.ts

@@ -0,0 +1,75 @@
+import type { InteractionBroker } from "./server/interaction-broker.js";
+import { INITIAL_MASTERY } from "./state/learning-state.js";
+import type { LearningStateStore, RecordAttemptInput, StartLearningInput } from "./state/learning-state.js";
+
+export interface AttemptEvaluation extends Omit<RecordAttemptInput, "misconception"> {
+  previousMastery: number;
+  newMastery: number;
+}
+
+/** 学习会话拥有评分资格、掌握度与交互生命周期的协调规则。 */
+export class LearningSession {
+  readonly state: LearningStateStore;
+  readonly broker: InteractionBroker;
+
+  constructor(state: LearningStateStore, broker: InteractionBroker) {
+    this.state = state;
+    this.broker = broker;
+  }
+
+  start(target: StartLearningInput): void {
+    if (!this.isCurrentTarget(target)) {
+      this.broker.reset("learning_target_changed");
+    }
+    this.state.start(target);
+  }
+
+  isCurrentTarget(target: StartLearningInput): boolean {
+    const current = this.state.snapshot();
+    return current.course?.id === target.course.id && current.topic?.id === target.topic.id;
+  }
+
+  stop(): void {
+    this.broker.cancelAll("learning_stopped");
+    this.state.stop();
+  }
+
+  resetTopic(): void {
+    this.broker.reset("learning_reset");
+    this.state.resetTopic();
+  }
+
+  resetForSession(): void {
+    this.broker.reset("session_changed");
+    this.state.resetForSession();
+  }
+
+  recordAttempt(input: RecordAttemptInput): AttemptEvaluation {
+    const completion = this.broker.getCompletion(input.interactionId);
+    if (completion === undefined) {
+      throw new Error(`Learning interaction ${input.interactionId} has not been resolved.`);
+    }
+    if (completion.skipped) {
+      throw new Error(`Learning interaction ${input.interactionId} was skipped.`);
+    }
+    const expectedEvidence = completion.type === "single_choice" || completion.type === "multi_choice"
+      ? "choice"
+      : completion.type;
+    if (input.evidenceType !== expectedEvidence) {
+      throw new Error(
+        `Evidence type ${input.evidenceType} does not match interaction ${input.interactionId} (${completion.type}); expected ${expectedEvidence}.`
+      );
+    }
+    const previousMastery = this.state.snapshot().concepts[input.conceptId]?.mastery ?? INITIAL_MASTERY;
+    const summary = this.state.recordAttempt(input);
+    const newMastery = this.state.snapshot().concepts[input.conceptId]?.mastery ?? previousMastery;
+    return {
+      interactionId: summary.interactionId,
+      conceptId: summary.conceptId,
+      outcome: summary.outcome,
+      evidenceType: summary.evidenceType,
+      previousMastery,
+      newMastery
+    };
+  }
+}

package/extension/runner/code-runner.ts

@@ -0,0 +1,275 @@
+// 可注入的本地代码 runner（规格 25）；不构成主机隔离，正式扩展默认禁用。
+//
+// 安全边界（每条都是硬约束，不是约定）：
+// - 语言白名单由程序定义（SUPPORTED_LANGUAGES），学习者只能选语言，不能指定
+//   executable / 参数；
+// - 源码写入临时目录（os.tmpdir() 下 pi-learn-*）的固定文件名 main.<ext>，
+//   文件名不含任何用户输入（防注入）；
+// - cwd 固定为该临时目录，不允许任意 cwd；
+// - 子进程 env 是显式白名单 MINIMAL_ENV，不继承完整 process.env，天然满足
+//   “不把 API key/敏感 env 传入子进程”；
+// - stdout/stderr 各上限 64KB，超出截断（truncated=true）但继续消费防死锁；
+// - 超时（默认 8s）kill；结束（含超时/报错/abort）后 finally 清理临时目录。
+//
+// 已知限制（MVP，规格 25 要求更成熟版本放 Docker/沙箱）：
+// - Windows 上 child.kill() 只能终止直接子进程，python 可能留下孤儿进程；
+//   升级路径：taskkill /T /F 按进程树杀，或整体移入容器；
+// - 无 CPU/内存资源限制：恶意代码可以忙等耗尽本机资源。
+
+import { spawn } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+import type { CodeRunRequest, CodeRunResult } from "../../shared/protocol.js";
+
+export const DEFAULT_TIMEOUT_MS = 8000;
+export const MAX_OUTPUT_BYTES = 64 * 1024;
+
+/** 超时 kill 后等待子进程退出的宽限时间；超过则直接返回 timedOut，避免请求挂起。 */
+const KILL_GRACE_MS = 1000;
+
+export interface LanguageConfig {
+  /** 要 spawn 的 executable；由程序定义，学习者不可控。 */
+  command: string;
+  /** 临时目录内源码文件的扩展名。 */
+  extension: string;
+}
+
+/** 固定允许语言表（规格 25：固定允许语言、命令模板程序定义）。 */
+export const SUPPORTED_LANGUAGES: Readonly<Record<string, LanguageConfig>> = {
+  python: { command: "python", extension: ".py" },
+  node: { command: "node", extension: ".js" }
+};
+
+export function isSupportedLanguage(language: string): boolean {
+  return Object.prototype.hasOwnProperty.call(SUPPORTED_LANGUAGES, language);
+}
+
+/**
+ * 子进程环境白名单。Windows 上 spawn 需要 PATH 与系统目录才能定位解释器
+ * （SystemRoot/WINDIR/COMSPEC）；TEMP/TMP 给子进程一个可写的临时位置。
+ * 明确不继承完整 process.env：API key、token 等敏感变量不会传入子进程。
+ */
+const MINIMAL_ENV: Readonly<Record<string, string>> = {
+  PATH: process.env.PATH ?? "",
+  SystemRoot: process.env.SystemRoot ?? "",
+  WINDIR: process.env.WINDIR ?? "",
+  TEMP: process.env.TEMP ?? "",
+  TMP: process.env.TMP ?? "",
+  COMSPEC: process.env.COMSPEC ?? ""
+};
+
+/** 可注入的测试配置；临时目录与环境白名单不限制代码访问宿主文件系统。 */
+export interface LocalCodeRunnerOptions {
+  /** 临时运行目录的父目录。默认 os.tmpdir()；可注入便于测试断言清理。 */
+  tmpRoot?: string;
+  /** 语言表覆盖（测试 seam，合并到内置白名单之上）。 */
+  languages?: Record<string, LanguageConfig>;
+}
+
+export interface CodeRunner {
+  run(request: CodeRunRequest, signal?: AbortSignal): Promise<CodeRunResult>;
+}
+
+/** 运行时缺失（spawn ENOENT）时的专用错误，server 映射为 503 runtime_unavailable。 */
+export class CodeRunUnavailableError extends Error {
+  readonly language: string;
+
+  constructor(language: string) {
+    super(`Runtime for "${language}" is not available on this machine.`);
+    this.name = "CodeRunUnavailableError";
+    this.language = language;
+  }
+}
+
+/** 按 64KB 上限截断收集一个输出流；截断后仍持续消费（防背压死锁）。 */
+class OutputCollector {
+  text = "";
+  truncated = false;
+  private readonly decoder = new StringDecoder("utf8");
+  private remaining = MAX_OUTPUT_BYTES;
+
+  push(chunk: Buffer): void {
+    if (this.truncated) {
+      return; // 仍在消费（防死锁），但不再缓冲
+    }
+    if (chunk.length > this.remaining) {
+      this.truncated = true;
+    }
+    const keep = Math.min(chunk.length, this.remaining);
+    if (keep > 0) {
+      this.text += this.decoder.write(chunk.subarray(0, keep));
+    }
+    this.remaining -= chunk.length;
+  }
+
+  end(): void {
+    this.text += this.decoder.end();
+  }
+}
+
+export class LocalCodeRunner implements CodeRunner {
+  private readonly languages: Readonly<Record<string, LanguageConfig | undefined>>;
+  private readonly tmpRoot: string;
+
+  constructor(options: LocalCodeRunnerOptions = {}) {
+    this.languages = { ...SUPPORTED_LANGUAGES, ...options.languages };
+    this.tmpRoot = options.tmpRoot ?? tmpdir();
+  }
+
+  async run(request: CodeRunRequest, signal?: AbortSignal): Promise<CodeRunResult> {
+    const config = Object.prototype.hasOwnProperty.call(this.languages, request.language)
+      ? this.languages[request.language]
+      : undefined;
+    if (config === undefined) {
+      throw new Error(`Unsupported language: ${request.language}.`);
+    }
+    const startedAt = Date.now();
+    const tmpDir = await mkdtemp(path.join(this.tmpRoot, "pi-learn-"));
+    try {
+      const filePath = path.join(tmpDir, `main${config.extension}`);
+      await writeFile(filePath, request.code, "utf8");
+      return await this.runProcess(
+        config.command,
+        filePath,
+        request.language,
+        tmpDir,
+        request.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        signal,
+        startedAt
+      );
+    } finally {
+      // 超时/报错/abort 路径也要清理；rm 失败（Windows 上孤儿进程占用文件）
+      // 只记录，不掩盖原始错误。
+      await rm(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 }).catch((error: unknown) => {
+        console.warn("[pi-learning] failed to clean up run dir:", tmpDir, error);
+      });
+    }
+  }
+
+  private runProcess(
+    command: string,
+    filePath: string,
+    language: string,
+    cwd: string,
+    timeoutMs: number,
+    signal: AbortSignal | undefined,
+    startedAt: number
+  ): Promise<CodeRunResult> {
+    return new Promise<CodeRunResult>((resolve, reject) => {
+      let child: ChildProcess;
+      try {
+        child = spawn(command, [filePath], {
+          cwd,
+          env: MINIMAL_ENV,
+          stdio: ["ignore", "pipe", "pipe"],
+          windowsHide: true
+        });
+      } catch (error) {
+        reject(error);
+        return;
+      }
+
+      let settled = false;
+      let timedOut = false;
+      let aborted = false;
+      let timer: NodeJS.Timeout | undefined;
+      let graceTimer: NodeJS.Timeout | undefined;
+
+      const finish = (result: CodeRunResult): void => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        clearTimeout(graceTimer);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(result);
+      };
+
+      const fail = (error: unknown): void => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        clearTimeout(graceTimer);
+        signal?.removeEventListener("abort", onAbort);
+        reject(error);
+      };
+
+      // abort 是调用方取消 → reject；超时是正常结果 → timedOut=true。二者语义不同。
+      const onAbort = (): void => {
+        aborted = true;
+        clearTimeout(timer);
+        clearTimeout(graceTimer);
+        child.kill();
+        // 等待 close 释放文件和工作目录；仍保留有界退出时间。
+        graceTimer = setTimeout(() => fail(new Error("Code run aborted.")), KILL_GRACE_MS);
+      };
+
+      const onTimeout = (): void => {
+        timedOut = true;
+        child.kill();
+        // Windows 上 kill 可能杀不掉（python 留孤儿）；最多再等 KILL_GRACE_MS，
+        // 之后直接 resolve timedOut，避免请求挂起。kill 后若子进程很快退出，
+        // close 分支会带着真实 exitCode 先 settle。
+        graceTimer = setTimeout(() => {
+          finish({
+            exitCode: null,
+            stdout: stdout.text,
+            stderr: stderr.text,
+            timedOut: true,
+            durationMs: Date.now() - startedAt,
+            truncated: stdout.truncated || stderr.truncated
+          });
+        }, KILL_GRACE_MS);
+      };
+
+      const stdout = new OutputCollector();
+      const stderr = new OutputCollector();
+      child.stdout?.on("data", (chunk: Buffer) => stdout.push(chunk));
+      child.stdout?.on("error", fail);
+      child.stderr?.on("data", (chunk: Buffer) => stderr.push(chunk));
+      child.stderr?.on("error", fail);
+
+      child.once("error", (error: NodeJS.ErrnoException) => {
+        if (error.code === "ENOENT") {
+          fail(new CodeRunUnavailableError(language));
+          return;
+        }
+        fail(error);
+      });
+
+      // close 在 stdio 全部关闭后触发，比 exit 可靠（exit 可能先于 stdout 结束）。
+      child.once("close", (exitCode) => {
+        stdout.end();
+        stderr.end();
+        if (aborted) {
+          fail(new Error("Code run aborted."));
+          return;
+        }
+        finish({
+          exitCode: exitCode ?? null,
+          stdout: stdout.text,
+          stderr: stderr.text,
+          timedOut,
+          durationMs: Date.now() - startedAt,
+          truncated: stdout.truncated || stderr.truncated
+        });
+      });
+
+      timer = setTimeout(onTimeout, timeoutMs);
+      if (signal !== undefined) {
+        if (signal.aborted) {
+          onAbort();
+          return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+    });
+  }
+}

package/extension/server/interaction-broker.ts

@@ -0,0 +1,345 @@
+import type {
+  InteractionSubmission,
+  LearningInteraction,
+  ResolvedAnswer,
+  SkippedResolvedAnswer,
+  SubmitResult
+} from "../../shared/protocol.js";
+import { validateInteractionAnswer } from "../utils/validation.js";
+
+/** Optional observability hooks; default is no-op so existing behavior is unchanged. */
+export interface BrokerListeners {
+  onPresented?: (interaction: LearningInteraction) => void;
+  onResolved?: (answer: ResolvedAnswer) => void;
+  onCancelled?: (interactionId: string, reason: string) => void;
+}
+
+interface PendingInteraction {
+  interaction: LearningInteraction;
+  resolve: (answer: ResolvedAnswer) => void;
+  reject: (error: Error) => void;
+  cleanup: () => void;
+}
+
+const MAX_RESOLVED_IDS = 1_000;
+
+export interface InteractionCompletion {
+  type: LearningInteraction["type"];
+  skipped: boolean;
+}
+
+export class InteractionCancelledError extends Error {
+  constructor(interactionId: string, reason: string) {
+    super(`Interaction ${interactionId} was cancelled: ${reason}.`);
+    this.name = "InteractionCancelledError";
+  }
+}
+
+export class InteractionConflictError extends Error {
+  constructor(interactionId: string, state: "pending" | "resolved" = "pending") {
+    super(
+      state === "pending"
+        ? `Interaction ${interactionId} is already pending.`
+        : `Interaction ${interactionId} has already been resolved.`
+    );
+    this.name = "InteractionConflictError";
+  }
+}
+
+export class InteractionBroker {
+  private readonly pending = new Map<string, PendingInteraction>();
+  private readonly resolvedIds = new Map<string, InteractionCompletion>();
+  private listeners: BrokerListeners;
+
+  constructor(listeners: BrokerListeners = {}) {
+    this.listeners = listeners;
+  }
+
+  /**
+   * Attach additional listeners (used by LearningServer after construction).
+   * Same-key listeners compose: an earlier onPresented keeps firing when a
+   * later one is added, so the SSE broadcast and the phase migration hook can
+   * coexist on one broker.
+   */
+  subscribe(listeners: BrokerListeners): void {
+    const onPresented = compose(
+      this.listeners.onPresented,
+      listeners.onPresented
+    );
+    const onResolved = compose(
+      this.listeners.onResolved,
+      listeners.onResolved
+    );
+    const onCancelled = compose(
+      this.listeners.onCancelled,
+      listeners.onCancelled
+    );
+    this.listeners = {
+      ...(onPresented === undefined ? {} : { onPresented }),
+      ...(onResolved === undefined ? {} : { onResolved }),
+      ...(onCancelled === undefined ? {} : { onCancelled })
+    };
+  }
+
+  present(
+    interaction: LearningInteraction,
+    signal?: AbortSignal
+  ): Promise<ResolvedAnswer> {
+    if (this.pending.has(interaction.id)) {
+      return Promise.reject(new InteractionConflictError(interaction.id));
+    }
+
+    if (this.resolvedIds.has(interaction.id)) {
+      return Promise.reject(
+        new InteractionConflictError(interaction.id, "resolved")
+      );
+    }
+
+    if (signal?.aborted) {
+      return Promise.reject(
+        new InteractionCancelledError(interaction.id, "aborted")
+      );
+    }
+
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        this.rejectPending(
+          interaction.id,
+          new InteractionCancelledError(interaction.id, "aborted"),
+          "aborted"
+        );
+      };
+      const cleanup = () => {
+        signal?.removeEventListener("abort", onAbort);
+      };
+
+      this.pending.set(interaction.id, { interaction, resolve, reject, cleanup });
+      signal?.addEventListener("abort", onAbort, { once: true });
+      notifyListener(() => this.listeners.onPresented?.(interaction));
+    });
+  }
+
+  submit(submission: InteractionSubmission): SubmitResult {
+    const pending = this.pending.get(submission.interactionId);
+    if (!pending) {
+      if (this.resolvedIds.has(submission.interactionId)) {
+        return {
+          ok: false,
+          reason: "already_resolved",
+          message: `Interaction ${submission.interactionId} has already been resolved.`
+        };
+      }
+
+      return {
+        ok: false,
+        reason: "not_found",
+        message: `No pending interaction with id ${submission.interactionId}.`
+      };
+    }
+
+    const validation = validateInteractionAnswer(
+      pending.interaction,
+      submission.answer
+    );
+    if (!validation.ok) {
+      return {
+        ok: false,
+        reason: "invalid_answer",
+        message: validation.message
+      };
+    }
+
+    const responseTimeMs = Math.max(
+      0,
+      Date.now() - pending.interaction.createdAt
+    );
+    let answer: ResolvedAnswer;
+    switch (validation.type) {
+      case "single_choice":
+        answer = {
+          interactionId: pending.interaction.id,
+          type: validation.type,
+          answer: validation.answer,
+          responseTimeMs
+        };
+        break;
+      case "multi_choice":
+        answer = {
+          interactionId: pending.interaction.id,
+          type: validation.type,
+          answer: validation.answer,
+          responseTimeMs
+        };
+        break;
+      case "free_response":
+        answer = {
+          interactionId: pending.interaction.id,
+          type: validation.type,
+          answer: validation.answer,
+          responseTimeMs
+        };
+        break;
+      case "code":
+        answer = {
+          interactionId: pending.interaction.id,
+          type: validation.type,
+          answer: validation.answer,
+          responseTimeMs
+        };
+        break;
+    }
+
+    this.pending.delete(submission.interactionId);
+    pending.cleanup();
+    this.rememberResolved(submission.interactionId, answer);
+    pending.resolve(answer);
+    notifyListener(() => this.listeners.onResolved?.(answer));
+    return { ok: true, answer };
+  }
+
+  /**
+   * Skip a pending interaction (spec 7.5 allowSkip). Resolves the pending
+   * promise with a SkippedResolvedAnswer so the tool result stays structured;
+   * rejects (skip_not_allowed) when the interaction does not allow skipping.
+   */
+  skip(interactionId: string): SubmitResult {
+    const pending = this.pending.get(interactionId);
+    if (!pending) {
+      if (this.resolvedIds.has(interactionId)) {
+        return {
+          ok: false,
+          reason: "already_resolved",
+          message: `Interaction ${interactionId} has already been resolved.`
+        };
+      }
+
+      return {
+        ok: false,
+        reason: "not_found",
+        message: `No pending interaction with id ${interactionId}.`
+      };
+    }
+
+    // Only single/multi choice carry allowSkip (spec 7.5); free response and
+    // code exercises cannot be skipped.
+    if (!("allowSkip" in pending.interaction && pending.interaction.allowSkip)) {
+      return {
+        ok: false,
+        reason: "skip_not_allowed",
+        message: `Interaction ${interactionId} does not allow skipping.`
+      };
+    }
+
+    const answer: SkippedResolvedAnswer = {
+      interactionId: pending.interaction.id,
+      type:
+        pending.interaction.type === "multi_choice"
+          ? "multi_choice"
+          : "single_choice",
+      skipped: true,
+      responseTimeMs: Math.max(0, Date.now() - pending.interaction.createdAt)
+    };
+    this.pending.delete(interactionId);
+    pending.cleanup();
+    this.rememberResolved(interactionId, answer);
+    pending.resolve(answer);
+    notifyListener(() => this.listeners.onResolved?.(answer));
+    return { ok: true, answer };
+  }
+
+  cancel(interactionId: string, reason: string): void {
+    this.rejectPending(
+      interactionId,
+      new InteractionCancelledError(interactionId, reason),
+      reason
+    );
+  }
+
+  cancelAll(reason: string): void {
+    for (const interactionId of [...this.pending.keys()]) {
+      this.cancel(interactionId, reason);
+    }
+  }
+
+  reset(reason: string): void {
+    this.cancelAll(reason);
+    this.resolvedIds.clear();
+  }
+
+  getPending(): LearningInteraction[] {
+    return [...this.pending.values()].map(({ interaction }) => interaction);
+  }
+
+  hasResolved(interactionId: string): boolean {
+    return this.resolvedIds.has(interactionId);
+  }
+
+  getCompletion(interactionId: string): InteractionCompletion | undefined {
+    const completion = this.resolvedIds.get(interactionId);
+    return completion === undefined ? undefined : { ...completion };
+  }
+
+  private rememberResolved(interactionId: string, answer: ResolvedAnswer): void {
+    // 资格凭据不保存代码/答案正文，避免在长会话中保留大块学习者输入。
+    this.resolvedIds.set(interactionId, { type: answer.type, skipped: "skipped" in answer });
+    if (this.resolvedIds.size <= MAX_RESOLVED_IDS) {
+      return;
+    }
+
+    const oldestId = this.resolvedIds.keys().next().value;
+    if (oldestId !== undefined) {
+      this.resolvedIds.delete(oldestId);
+    }
+  }
+
+  private rejectPending(
+    interactionId: string,
+    error: Error,
+    cancellationReason?: string
+  ): void {
+    const pending = this.pending.get(interactionId);
+    if (!pending) {
+      return;
+    }
+
+    this.pending.delete(interactionId);
+    pending.cleanup();
+    pending.reject(error);
+    if (cancellationReason !== undefined) {
+      notifyListener(() =>
+        this.listeners.onCancelled?.(interactionId, cancellationReason)
+      );
+    }
+  }
+}
+
+/**
+ * Compose two optional listeners into one: both fire in registration order.
+ * Used by subscribe so multiple subscribers share one broker (server SSE +
+ * state phase hooks). Throwing listeners are already contained by the
+ * notifyListener wrapper at the call sites.
+ */
+function compose<A extends unknown[]>(
+  first: ((...args: A) => void) | undefined,
+  second: ((...args: A) => void) | undefined
+): ((...args: A) => void) | undefined {
+  if (first === undefined) {
+    return second;
+  }
+  if (second === undefined) {
+    return first;
+  }
+  return (...args: A) => {
+    first(...args);
+    second(...args);
+  };
+}
+
+/** Listeners are observability hooks: a throwing listener must not break the broker. */
+function notifyListener(notify: () => void): void {
+  try {
+    notify();
+  } catch (error) {
+    console.error("InteractionBroker listener failed:", error);
+  }
+}