pi-learning-agent 0.1.0

package/extension/tools/ask-free-response.ts

@@ -0,0 +1,88 @@
+import {
+  defineTool,
+  type ExtensionContext
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import type {
+  FreeResponseInteraction,
+  FreeResponseResolvedAnswer
+} from "../../shared/protocol.js";
+import { createInteractionId } from "../utils/ids.js";
+import { presentFreeResponseInTui } from "./tui-presenter.js";
+
+const parameters = Type.Object({
+  question: Type.String({ minLength: 1 }),
+  placeholder: Type.Optional(Type.String()),
+  multiline: Type.Optional(Type.Boolean()),
+  conceptId: Type.Optional(Type.String({ minLength: 1 }))
+});
+
+export interface FreeResponseToolDetails extends FreeResponseResolvedAnswer {
+  conceptId?: string;
+}
+
+export type FreeResponsePresenter = (
+  interaction: FreeResponseInteraction,
+  signal: AbortSignal | undefined,
+  ctx: ExtensionContext
+) => Promise<FreeResponseResolvedAnswer>;
+
+export interface FreeResponseToolDependencies {
+  createId?: () => string;
+  now?: () => number;
+  present?: FreeResponsePresenter;
+}
+
+export function createAskFreeResponseTool(
+  dependencies: FreeResponseToolDependencies = {}
+) {
+  const createId = dependencies.createId ?? (() => createInteractionId("free"));
+  const now = dependencies.now ?? Date.now;
+  const present =
+    dependencies.present ??
+    ((interaction, signal, ctx) =>
+      presentFreeResponseInTui(interaction, signal, ctx, now));
+
+  return defineTool<typeof parameters, FreeResponseToolDetails>({
+    name: "learning_ask_free_response",
+    label: "Learning: Free Response",
+    description:
+      "Ask the learner an open-ended question and wait for their structured response.",
+    promptSnippet: "Ask a structured open-ended learning question",
+    executionMode: "sequential",
+    parameters,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const interaction: FreeResponseInteraction = {
+        id: createId(),
+        type: "free_response",
+        question: params.question,
+        multiline: params.multiline ?? true,
+        createdAt: now(),
+        ...(params.placeholder === undefined
+          ? {}
+          : { placeholder: params.placeholder }),
+        ...(params.conceptId === undefined
+          ? {}
+          : { conceptId: params.conceptId })
+      };
+      const resolved = await present(interaction, signal, ctx);
+      const details: FreeResponseToolDetails = {
+        ...resolved,
+        ...(interaction.conceptId === undefined
+          ? {}
+          : { conceptId: interaction.conceptId })
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Learner submitted this free response:\n${resolved.answer.text}\n(interaction ${resolved.interactionId})`
+          }
+        ],
+        details
+      };
+    }
+  });
+}

package/extension/tools/ask-multi-choice.ts

@@ -0,0 +1,109 @@
+import {
+  defineTool,
+  type ExtensionContext
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import type {
+  MultiChoiceAnswer,
+  MultiChoiceInteraction
+} from "../../shared/protocol.js";
+import { createInteractionId } from "../utils/ids.js";
+import { presentMultiChoiceInTui } from "./tui-presenter.js";
+import type { MultiChoiceResolvedAnswerOrSkip } from "./tui-presenter.js";
+
+const parameters = Type.Object({
+  title: Type.Optional(Type.String({ minLength: 1 })),
+  question: Type.String({ minLength: 1 }),
+  options: Type.Array(
+    Type.Object({
+      id: Type.String({ minLength: 1 }),
+      label: Type.String({ minLength: 1 })
+    }),
+    { minItems: 2 }
+  ),
+  conceptId: Type.Optional(Type.String({ minLength: 1 })),
+  allowSkip: Type.Optional(Type.Boolean())
+});
+
+/**
+ * Answered or skipped (spec 7.5): a skipped interaction carries
+ * `skipped: true` and no answer.
+ */
+export type MultiChoiceToolDetails = (
+  | { interactionId: string; type: "multi_choice"; answer: MultiChoiceAnswer; responseTimeMs: number }
+  | { interactionId: string; type: "multi_choice"; skipped: true; responseTimeMs: number }
+) & { conceptId?: string };
+
+export interface MultiChoiceToolDependencies {
+  createId?: () => string;
+  now?: () => number;
+  present?: MultiChoicePresenter;
+}
+
+export type MultiChoicePresenter = (
+  interaction: MultiChoiceInteraction,
+  signal: AbortSignal | undefined,
+  ctx: ExtensionContext
+) => Promise<MultiChoiceResolvedAnswerOrSkip>;
+
+export function createAskMultiChoiceTool(
+  dependencies: MultiChoiceToolDependencies = {}
+) {
+  const createId =
+    dependencies.createId ?? (() => createInteractionId("multi"));
+  const now = dependencies.now ?? Date.now;
+  const present =
+    dependencies.present ??
+    ((interaction, signal, ctx) =>
+      presentMultiChoiceInTui(interaction, signal, ctx, now));
+
+  return defineTool<typeof parameters, MultiChoiceToolDetails>({
+    name: "learning_ask_multi_choice",
+    label: "Learning: Multi Choice",
+    description:
+      "Ask the learner a multi-choice question (one or more answers may be correct) and wait for their structured answer. allowSkip lets the learner decline without answering.",
+    promptSnippet: "Ask a structured multi-choice learning question",
+    executionMode: "sequential",
+    parameters,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const interaction: MultiChoiceInteraction = {
+        id: createId(),
+        type: "multi_choice",
+        question: params.question,
+        options: params.options,
+        allowSkip: params.allowSkip ?? false,
+        createdAt: now(),
+        ...(params.title === undefined ? {} : { title: params.title }),
+        ...(params.conceptId === undefined
+          ? {}
+          : { conceptId: params.conceptId })
+      };
+      const resolved = await present(interaction, signal, ctx);
+      const skipped = "skipped" in resolved;
+      const details: MultiChoiceToolDetails = {
+        interactionId: resolved.interactionId,
+        type: "multi_choice",
+        ...(skipped
+          ? { skipped: true }
+          : { answer: resolved.answer }),
+        responseTimeMs: resolved.responseTimeMs,
+        ...(interaction.conceptId === undefined
+          ? {}
+          : { conceptId: interaction.conceptId })
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: skipped
+              ? `Learner skipped the question (interaction ${resolved.interactionId}).`
+              : `Learner selected options ${resolved.answer.optionIds.join(", ")} (interaction ${resolved.interactionId}).`
+          }
+        ],
+        details
+      };
+    }
+  });
+}

package/extension/tools/ask-record-attempt.ts

@@ -0,0 +1,50 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { LearningSession, AttemptEvaluation } from "../learning-session.js";
+
+const parameters = Type.Object({
+  interactionId: Type.String({ minLength: 1 }),
+  conceptId: Type.String({ minLength: 1 }),
+  outcome: StringEnum(["correct", "partial", "incorrect"] as const),
+  evidenceType: StringEnum(["choice", "free_response", "code"] as const),
+  explanation: Type.String({
+    minLength: 1,
+    pattern: "\\S",
+    description: "Learner-facing explanation of the correct answer and key reasoning, in the learner's language. Shown with the outcome before the next question."
+  }),
+  misconception: Type.Optional(Type.String({ minLength: 1 }))
+});
+
+export interface RecordAttemptToolDetails extends AttemptEvaluation {
+  explanation: string;
+}
+
+/** Pi adapter：只负责参数与结果文案，评分规则属于 LearningSession。 */
+export function createAskRecordAttemptTool(session: Pick<LearningSession, "recordAttempt">) {
+  return defineTool<typeof parameters, RecordAttemptToolDetails>({
+    name: "learning_record_attempt",
+    label: "Learning: Record Attempt",
+    description:
+      "Record the learner's attempt on a concept after evaluating a learning_ask_* answer. Always include an explanation of the correct answer and key reasoning in the learner's language; the workspace displays it with the outcome. Complete this feedback before asking the next question. Do NOT record attempts for interactions whose tool result says skipped: true — a skipped question is not an answer.",
+    promptSnippet: "Record the learner's attempt with an explanation and update concept mastery",
+    parameters,
+    async execute(_toolCallId, params) {
+      const details: RecordAttemptToolDetails = {
+        ...session.recordAttempt(params),
+        explanation: params.explanation
+      };
+      const { previousMastery, newMastery } = details;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Recorded attempt for concept ${params.conceptId}: ${params.outcome} (${previousMastery.toFixed(2)} → ${newMastery.toFixed(2)}).`
+          }
+        ],
+        details
+      };
+    }
+  });
+}

package/extension/tools/ask-single-choice.ts

@@ -0,0 +1,110 @@
+import {
+  defineTool,
+  type ExtensionContext
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import type {
+  SingleChoiceAnswer,
+  SingleChoiceInteraction
+} from "../../shared/protocol.js";
+import { createInteractionId } from "../utils/ids.js";
+import { presentSingleChoiceInTui } from "./tui-presenter.js";
+import type { ChoiceResolvedAnswer } from "./tui-presenter.js";
+
+const parameters = Type.Object({
+  title: Type.Optional(Type.String({ minLength: 1 })),
+  question: Type.String({ minLength: 1 }),
+  options: Type.Array(
+    Type.Object({
+      id: Type.String({ minLength: 1 }),
+      label: Type.String({ minLength: 1 })
+    }),
+    { minItems: 2 }
+  ),
+  conceptId: Type.Optional(Type.String({ minLength: 1 })),
+  allowSkip: Type.Optional(Type.Boolean())
+});
+
+/**
+ * Answered or skipped (spec 7.5): a skipped interaction carries
+ * `skipped: true` and no answer, so the model can tell a decline from a
+ * wrong answer.
+ */
+export type SingleChoiceToolDetails = (
+  | { interactionId: string; type: "single_choice"; answer: SingleChoiceAnswer; responseTimeMs: number }
+  | { interactionId: string; type: "single_choice"; skipped: true; responseTimeMs: number }
+) & { conceptId?: string };
+
+export interface SingleChoiceToolDependencies {
+  createId?: () => string;
+  now?: () => number;
+  present?: SingleChoicePresenter;
+}
+
+export type SingleChoicePresenter = (
+  interaction: SingleChoiceInteraction,
+  signal: AbortSignal | undefined,
+  ctx: ExtensionContext
+) => Promise<ChoiceResolvedAnswer>;
+
+export function createAskSingleChoiceTool(
+  dependencies: SingleChoiceToolDependencies = {}
+) {
+  const createId =
+    dependencies.createId ?? (() => createInteractionId("choice"));
+  const now = dependencies.now ?? Date.now;
+  const present =
+    dependencies.present ??
+    ((interaction, signal, ctx) =>
+      presentSingleChoiceInTui(interaction, signal, ctx, now));
+
+  return defineTool<typeof parameters, SingleChoiceToolDetails>({
+    name: "learning_ask_single_choice",
+    label: "Learning: Single Choice",
+    description:
+      "Ask the learner one single-choice question and wait for their structured answer. allowSkip lets the learner decline without answering.",
+    promptSnippet: "Ask a structured single-choice learning question",
+    executionMode: "sequential",
+    parameters,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const interaction: SingleChoiceInteraction = {
+        id: createId(),
+        type: "single_choice",
+        question: params.question,
+        options: params.options,
+        allowSkip: params.allowSkip ?? false,
+        createdAt: now(),
+        ...(params.title === undefined ? {} : { title: params.title }),
+        ...(params.conceptId === undefined
+          ? {}
+          : { conceptId: params.conceptId })
+      };
+      const resolved = await present(interaction, signal, ctx);
+      const skipped = "skipped" in resolved;
+      const details: SingleChoiceToolDetails = {
+        interactionId: resolved.interactionId,
+        type: "single_choice",
+        ...(skipped
+          ? { skipped: true }
+          : { answer: resolved.answer }),
+        responseTimeMs: resolved.responseTimeMs,
+        ...(interaction.conceptId === undefined
+          ? {}
+          : { conceptId: interaction.conceptId })
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: skipped
+              ? `Learner skipped the question (interaction ${resolved.interactionId}).`
+              : `Learner selected option ${resolved.answer.optionId} (interaction ${resolved.interactionId}).`
+          }
+        ],
+        details
+      };
+    }
+  });
+}

package/extension/tools/index.ts

@@ -0,0 +1,39 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { LearningSession } from "../learning-session.js";
+import type { LearningServer } from "../server/learning-server.js";
+import { createAskCodeTool } from "./ask-code.js";
+import { createAskFreeResponseTool } from "./ask-free-response.js";
+import { createAskMultiChoiceTool } from "./ask-multi-choice.js";
+import { createAskRecordAttemptTool } from "./ask-record-attempt.js";
+import { createAskSingleChoiceTool } from "./ask-single-choice.js";
+import { createModeAwarePresenter } from "./tui-presenter.js";
+
+export interface LearningToolRegistrationDependencies {
+  session: LearningSession;
+  /** Source of hasWebClient() for uiMode auto routing (spec 28). */
+  server: LearningServer;
+}
+
+export function registerLearningTools(
+  pi: ExtensionAPI,
+  dependencies: LearningToolRegistrationDependencies
+): void {
+  const presenter = createModeAwarePresenter(
+    dependencies.session.broker,
+    () => dependencies.server.hasWebClient()
+  );
+  pi.registerTool(
+    createAskSingleChoiceTool({ present: presenter.presentSingleChoice })
+  );
+  pi.registerTool(
+    createAskMultiChoiceTool({ present: presenter.presentMultiChoice })
+  );
+  pi.registerTool(
+    createAskFreeResponseTool({ present: presenter.presentFreeResponse })
+  );
+  pi.registerTool(createAskCodeTool({ present: presenter.presentCode }));
+  pi.registerTool(
+    createAskRecordAttemptTool(dependencies.session)
+  );
+}