Shell/core import law: public API barrels + ESLint enforcement (stage 2)

The shell now imports through exactly two barrels, enforced by
import/no-restricted-paths (npm run lint):

  components/**  ->  "@/src/core"      (pure core API, browser-safe)
  app/**         ->  "@/src/core" + "@/src/server" (server entries)

Zone violations are lint errors with architecture-pointer messages; the
pure-core modules (contracts, question-core, plan-tree, phases, pending,
math-delims, ui-message) may never import agent/server/store.

Supporting moves (direction: IO layers -> core):
- core/index.ts: the core public API barrel
- core/ui-message.ts: moved from src/agent (it was shell-facing all along)
- quiz/ask input zod schemas moved agent/tools -> core/question-core
  (the question contract, alongside the grading logic)
- ChatRecord/ChatSummary moved store/chats -> core/contracts (single schema)
- GraphSnapshot/NodeStateClass moved core/graph -> core/contracts (the
  /api/graph payload IS a contract; the pure renderer needs only these)
- src/server/{chats,graph,jobs}.ts + index.ts: thin server entries for the
  transport layer; GET /api/graph's fold side-effect now lives behind
  graphView() instead of inline in the route

Gates: tsc clean, 190/190 tests, eslint clean (law verified to fire on
store/agent/subpath violations), production build clean.

(Repo repair en route: a git object (app/chat/[id] tree) was missing from
the object store — reconstructed byte-exactly via mktree from its blob;
the broken node_modules that stalled the build was cleanly reinstalled.)
This commit is contained in:
Amos
2026-08-31 19:51:17 +03:00
parent bfb31568fc
commit e92140f993
37 changed files with 4506 additions and 171 deletions
+4 -59
View File
@@ -1,5 +1,5 @@
import { tool, type ToolSet } from "ai";
import { z } from "zod";
import { askInputSchema, quizInputSchema } from "../core/question-core.ts";
import { jobTools } from "./tools/jobs.ts";
import { planTools } from "./tools/plan.ts";
@@ -9,67 +9,15 @@ import { planTools } from "./tools/plan.ts";
* - questionTools (quiz / ask_user_question): CLIENT-SIDE tools (no `execute`).
* The tool call streams to the browser in `input-available` state; the
* learner answers in the dock; the client grades via question-core and
* sends the verdict with addToolOutput.
* sends the verdict with addToolOutput. The input schemas live in
* core/question-core (the question contract) — parameter names mirror
* the prompt docs exactly; keep them in sync.
* - planTools (src/agent/tools/plan.ts): SERVER-SIDE, mutate the chat's plan
* tree (needs the chatId closure — hence the per-request factory).
* - jobTools (src/agent/tools/jobs.ts): CLIENT-SIDE semantics, server-side
* fulfillment by background sub-agents (see src/core/contracts.ts).
*
* Parameter names mirror the prompt docs exactly — keep them in sync.
*/
const optionSchema = z.object({
label: z.string().describe("Display label for the answer option"),
value: z
.string()
.optional()
.describe("Optional machine-readable value returned for the option. Defaults to the label."),
description: z.string().optional().describe("Optional extra detail shown below the option"),
});
// Raw schemas stay exported: `tool()` wraps them into its internal Schema
// type (erasing z.infer), so clients infer input types from these instead.
export const quizInputSchema = z.object({
question: z.string().describe("The single quiz question to ask"),
options: z
.array(optionSchema)
.min(2)
.describe("The answer options (2 or more). Options only — no free-text mode. Never add your own 'I don't know' option."),
correctAnswer: z
.union([z.string(), z.array(z.string())])
.describe(
"The correct answer as the option value(s) — the `value` field of the option you intend. " +
"Single-select: one string. Multi-select: an array; the learner is only correct if their selection matches this set exactly.",
),
explanation: z
.string()
.describe("Explanation revealed AFTER the learner answers. Always say why the correct answer is correct."),
multiSelect: z.boolean().optional().describe("Set true only when more than one option is correct"),
details: z.string().optional().describe("Optional extra context or instructions shown under the question"),
nodeId: z
.string()
.optional()
.describe(
"Optional plan-tree node id this question assesses. Set whenever the question targets a tree node — " +
"the outcome feeds the learner's knowledge graph. Omit for ad-hoc probes.",
),
});
export const askInputSchema = z.object({
question: z.string().describe("The single question to ask"),
mode: z
.enum(["single-select", "multi-select", "text"])
.optional()
.describe("Answer mode. Omit for single-select when options are given, or text when they are not."),
options: z
.array(optionSchema)
.min(2)
.optional()
.describe("Optional multiple-choice options. Omit for free-form text input. The learner can always choose 'Other' and type a custom answer."),
multiSelect: z.boolean().optional().describe("Set true to allow multiple answers to be selected"),
details: z.string().optional().describe("Optional extra context or instructions shown under the question"),
});
export const quizTool = tool({
description:
"Ask the learner a GRADED question with a known correct answer, then instantly grade and give feedback. " +
@@ -108,6 +56,3 @@ export function createTeacherTools(ctx: TeacherToolContext): ToolSet {
...jobTools(ctx),
};
}
export type QuizToolInput = z.infer<typeof quizInputSchema>;
export type AskToolInput = z.infer<typeof askInputSchema>;