@khorsheed/dsh-library 0.0.0-stage → 0.1.1

package/lib/tool.js

@@ -0,0 +1,1597 @@
+import { U as isThickResource, V as formatLocator, j as LIBRARY_RESOURCE_KINDS, r as masteryReason, t as profileOf, x as normalizeQuizOptions } from "./profiles-CFrPQdfO.js";
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/image-refs.js
+/** How many sessions are remembered. */
+const SESSIONS = 200;
+/** The id without its digest prefix, for matching what the model wrote. */
+function bareId(id) {
+	return id.replace(/^sha256:/, "");
+}
+/** A whole reference, when a value carries every field. */
+function asAttachmentRef(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const ref = value;
+	if (typeof ref.attachmentId !== "string" || typeof ref.mediaType !== "string") return void 0;
+	if (typeof ref.bytes !== "number" || ref.bytes <= 0) return void 0;
+	if (typeof ref.width !== "number" || typeof ref.height !== "number") return void 0;
+	return {
+		attachmentId: ref.attachmentId,
+		mediaType: ref.mediaType,
+		bytes: ref.bytes,
+		width: ref.width,
+		height: ref.height
+	};
+}
+/** The image references each session's user messages carried, newest last. */
+var ImageRefCache = class {
+	bySession = /* @__PURE__ */ new Map();
+	/** Remember the images one committed event carries (non-image events are ignored). */
+	observe(sessionId, event) {
+		if (event.type !== "user/message") return;
+		const content = event.data?.content;
+		if (!Array.isArray(content)) return;
+		for (const block of content) {
+			if (block?.type !== "image") continue;
+			const ref = asAttachmentRef(block.attachment);
+			if (ref !== void 0) this.remember(sessionId, ref);
+		}
+	}
+	remember(sessionId, ref) {
+		const kept = (this.bySession.get(sessionId) ?? []).filter((entry) => entry.attachmentId !== ref.attachmentId);
+		kept.push(ref);
+		this.bySession.delete(sessionId);
+		this.bySession.set(sessionId, kept.slice(-20));
+		while (this.bySession.size > SESSIONS) this.bySession.delete(this.bySession.keys().next().value);
+	}
+	/**
+	* The whole reference for what the model wrote: a complete reference
+	* passes through; an id (with or without its prefix) is looked up; nothing
+	* at all means the session's latest photo.
+	*/
+	resolve(sessionId, written) {
+		const whole = asAttachmentRef(written);
+		const known = sessionId === void 0 ? [] : this.bySession.get(sessionId) ?? [];
+		const id = typeof written === "string" ? written : typeof written?.attachmentId === "string" ? written.attachmentId : void 0;
+		if (id !== void 0) {
+			const match = known.find((ref) => bareId(ref.attachmentId) === bareId(id));
+			if (match !== void 0) return match;
+		}
+		if (whole !== void 0) return whole;
+		return id === void 0 ? known.at(-1) : void 0;
+	}
+};
+//#endregion
+//#region lib/types/tools/kit.js
+/** JSON pass-through output — what the render emits IS what the model reads, so it goes compact (indentation doubled every result). */
+function jsonOutput() {
+	return {
+		schema: { type: "json" },
+		render: (_args, value) => [{
+			type: "text",
+			text: JSON.stringify(value)
+		}]
+	};
+}
+/** Unwrap a service outcome: the domain value, or a thrown Error whose message IS the lesson. */
+function unwrap(outcome) {
+	if (outcome.ok) return outcome;
+	throw new Error(outcome.message);
+}
+const READ_WHATS = [
+	"projects",
+	"resources",
+	"toc",
+	"roadmap",
+	"pages",
+	"cards",
+	"quiz"
+];
+/** The calling session's id, when the call came from a session. */
+function sessionIdOf(exec) {
+	const id = exec?.agent?.session?.id;
+	return id === void 0 ? void 0 : String(id);
+}
+/**
+* Payloads arrive as objects — or, from models that stringify deep parameters
+* (common with big nested ones), as their JSON text; both parse. A refusal
+* names what actually arrived, so the model fixes the transport instead of
+* guessing at the shape.
+*/
+function payload(value) {
+	if (typeof value === "string") try {
+		value = JSON.parse(value);
+	} catch {
+		return;
+	}
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function payloadList(value) {
+	if (typeof value === "string") try {
+		value = JSON.parse(value);
+	} catch {
+		return;
+	}
+	if (Array.isArray(value)) return value;
+	const items = payload(value)?.items;
+	return Array.isArray(items) ? items : void 0;
+}
+function arrival(field, value) {
+	if (value === void 0) return `no ${field} field arrived — set the ${field} field itself; its value may be the object or its JSON text`;
+	if (typeof value === "string") try {
+		JSON.parse(value);
+		return `${field} arrived as JSON text that is not the expected shape`;
+	} catch {
+		return `${field} arrived as text that is not valid JSON — send the object itself (or its JSON text)`;
+	}
+	return `${field} arrived as ${Array.isArray(value) ? "an array" : typeof value} with an unexpected shape`;
+}
+/**
+* A contents sent as one text: one row per line. Models also join the rows
+* with ；/; on a single line, or send literal "\\n" escapes — a single line
+* holding several separators splits on them (a 30-chapter book once landed
+* as ONE row, and every station's chapters then fell out of range).
+*/
+function splitTocText(text) {
+	const lines = text.replace(/\\n/g, "\n").split("\n").map((line) => line.trim()).filter((line) => line !== "");
+	if (lines.length !== 1) return lines;
+	const parts = lines[0].split(/\s*[；;]\s*/).map((part) => part.trim()).filter((part) => part !== "");
+	return parts.length >= 3 ? parts : lines;
+}
+/**
+* A station's chapters as a locator: row numbers and ranges, whatever the
+* dash or separator ("15–16", "3-4、7", "第3-4章"); words around them (an
+* appendix, a part name) come back as `rest` for a topic side reference.
+*/
+function chaptersLocator(chapters) {
+	const normalized = chapters.replace(/[–—~～至到]/g, "-").replace(/[，、；;/]/g, ",");
+	const ranges = [...normalized.matchAll(/(\d+)\s*(?:-\s*(\d+))?/g)].map((match) => match[2] === void 0 ? match[1] : `${match[1]}-${match[2]}`);
+	const rest = normalized.replace(/(\d+)\s*(?:-\s*(\d+))?/g, "").replace(/[第章节,+\s-]+/g, " ").trim();
+	return {
+		locator: ranges.join(","),
+		...rest === "" ? {} : { rest }
+	};
+}
+/** The first non-blank string of the candidates (the resource/book alias pairs). */
+function pickString(...values) {
+	return values.find((value) => typeof value === "string" && value.trim() !== "")?.trim();
+}
+/**
+* One cover argument → the stored `{ ref, locator?, … }`. Accepts the string
+* shorthand ("r_…#1-5" | "https://…" | "topic: …"), the v5 object, and every
+* legacy union member ({ kind: "book", bookId|book, ranges } |
+* { kind: "resource", resourceId|resource } | { kind: "url", url, title? } |
+* { kind: "topic", text }). Undefined when nothing usable arrived.
+*/
+function normalizeCoverArg(value) {
+	if (typeof value === "string") {
+		const shorthand = value.trim();
+		if (shorthand === "") return void 0;
+		if (shorthand.startsWith("topic:") || /^https?:\/\//.test(shorthand)) return { ref: shorthand };
+		const match = /^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:#\s*(.+))?$/.exec(shorthand);
+		return {
+			ref: match?.[1] ?? shorthand,
+			...match?.[2] === void 0 ? {} : { locator: match[2].trim() }
+		};
+	}
+	const record = payload(value);
+	if (record === void 0) return void 0;
+	const provenance = {
+		...typeof record.by === "string" ? { by: record.by } : {},
+		...typeof record.verifiedAt === "string" ? { verifiedAt: record.verifiedAt } : {}
+	};
+	if (typeof record.ref === "string" && record.ref.trim() !== "") return {
+		ref: record.ref.trim(),
+		...typeof record.locator === "string" && record.locator.trim() !== "" ? { locator: record.locator.trim() } : {},
+		...typeof record.title === "string" && record.title.trim() !== "" ? { title: record.title.trim() } : {},
+		...provenance
+	};
+	const bookId = pickString(record.bookId, record.book);
+	if ((record.kind === "book" || record.kind === void 0) && bookId !== void 0) {
+		const ranges = Array.isArray(record.ranges) ? record.ranges.flatMap((range) => {
+			const row = payload(range);
+			const from = typeof row?.from === "number" ? row.from : void 0;
+			const to = typeof row?.to === "number" ? row.to : void 0;
+			return from === void 0 || to === void 0 ? [] : [{
+				from,
+				to
+			}];
+		}) : [];
+		return {
+			ref: bookId,
+			...ranges.length === 0 ? {} : { locator: formatLocator(ranges) },
+			...provenance
+		};
+	}
+	const resourceId = pickString(record.resourceId, record.resource);
+	if (record.kind === "resource" && resourceId !== void 0) return {
+		ref: resourceId,
+		...provenance
+	};
+	if (record.kind === "url" && typeof record.url === "string") return {
+		ref: record.url,
+		...typeof record.title === "string" ? { title: record.title } : {},
+		...provenance
+	};
+	if (record.kind === "topic" && typeof record.text === "string") return {
+		ref: `topic:${record.text}`,
+		...provenance
+	};
+}
+/**
+* A question's two axes are optional on the wire: target defaults to the
+* station's topic, evidence to domain knowledge. Flat shorthands fill them in —
+* cardIds imply a marked target; pageId / url imply photo / web evidence; a
+* bare string sets just the kind. The service's two-axis gate is untouched: it
+* judges the normalized shape.
+*/
+function normalizeQuestionAxes(question) {
+	const { cardIds, quote, url, pageId, ...rest } = question;
+	const flatIds = Array.isArray(cardIds) ? cardIds.filter((id) => typeof id === "string" && id !== "") : void 0;
+	const rawTarget = typeof rest.target === "string" ? { kind: rest.target } : rest.target;
+	let target = (rawTarget !== null && typeof rawTarget === "object" && !Array.isArray(rawTarget) ? rawTarget : void 0) ?? (flatIds !== void 0 && flatIds.length > 0 ? { kind: "marked" } : { kind: "topic" });
+	if (flatIds !== void 0 && flatIds.length > 0 && target.cardIds === void 0) target = {
+		...target,
+		cardIds: flatIds
+	};
+	const rawEvidence = typeof rest.evidence === "string" ? { kind: rest.evidence } : rest.evidence;
+	let evidence = (rawEvidence !== null && typeof rawEvidence === "object" && !Array.isArray(rawEvidence) ? rawEvidence : void 0) ?? { kind: typeof pageId === "string" && pageId !== "" ? "photo" : typeof url === "string" && url !== "" ? "web" : "knowledge" };
+	for (const [key, value] of [
+		["quote", quote],
+		["url", url],
+		["pageId", pageId]
+	]) if (typeof value === "string" && value !== "" && evidence[key] === void 0) evidence = {
+		...evidence,
+		[key]: value
+	};
+	return {
+		...rest,
+		target,
+		evidence
+	};
+}
+/**
+* The roadmap nodes schema. Only the canonical shape is advertised; execute
+* still takes the older spellings (also, dependsOn, read stations, acceptance
+* refs, chapterRanges, covers) — the schema items allow extra keys, and the
+* JSON-text branch lets a stringified list through to execute's parser.
+*/
+const NODES_SCHEMA = { oneOf: [{
+	type: "array",
+	items: {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			id: {
+				type: "string",
+				description: "Unique: s1, s2…"
+			},
+			title: { type: "string" },
+			chapters: {
+				oneOf: [{ type: "string" }, { type: "integer" }],
+				description: "Contents rows it covers: \"4\" | \"3-4\"."
+			},
+			points: {
+				type: "array",
+				description: "Required: its 3–5 knowledge points — the chapter quiz asks them.",
+				items: {
+					type: "object",
+					additionalProperties: true,
+					properties: {
+						id: {
+							type: "string",
+							description: "A stable slug."
+						},
+						title: { type: "string" }
+					}
+				}
+			},
+			goals: {
+				type: "json",
+				description: "What the learner can do after it: [\"…\"]."
+			}
+		}
+	}
+}, {
+	type: "string",
+	description: "The same list as JSON text."
+}] };
+/**
+* The quiz questions schema. ids are numbered when missing; target and
+* evidence follow from cardIds / quote / pageId / url and the textbook (the
+* full two-axis objects still parse).
+*/
+const QUESTIONS_SCHEMA = { oneOf: [{
+	type: "array",
+	items: {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			point: {
+				type: "string",
+				description: "The station point it probes."
+			},
+			kind: {
+				type: "string",
+				enum: [
+					"choice",
+					"fill",
+					"free"
+				]
+			},
+			prompt: { type: "string" },
+			options: {
+				type: "json",
+				description: "choice only: [\"…\", \"…\"]."
+			},
+			answer: {
+				type: "string",
+				description: "choice: the right option, verbatim."
+			},
+			explanation: { type: "string" },
+			quote: {
+				type: "string",
+				description: "The page text it rests on (required for a material textbook)."
+			}
+		}
+	}
+}, {
+	type: "string",
+	description: "The same list as JSON text."
+}] };
+/** The per-call helpers every tool closes over, built once per tool set. */
+function createToolKit(service, images) {
+	/** The session's binding, when it has one. */
+	const bindingOf = (exec) => {
+		const sessionId = sessionIdOf(exec);
+		return sessionId === void 0 ? void 0 : service.getBinding(sessionId);
+	};
+	/** The project: the argument, else the binding, else the resource's owner, else a lesson. */
+	const projectOf = (value, exec, resource) => {
+		if (typeof value === "string" && value.trim() !== "") return value.trim();
+		const bound = bindingOf(exec)?.projectId;
+		if (bound !== void 0) return bound;
+		if (resource !== void 0) {
+			const owner = service.findResourceOwner(resource);
+			if (owner !== void 0) return owner;
+		}
+		throw new Error("no project: this session is not bound to one and no resource resolves one — library_read · projects lists them; ask the learner which one (ask_user_question), then library_binding { project, resource? }");
+	};
+	/** A successful write knows its work context: an unbound session binds to it, and a project-bound session picks up the resource it just registered — create the project, register the book, draft the path, and the chain has strung itself. Never steals another project's session, never yanks a resource off one. */
+	const autoBind = async (exec, binding) => {
+		const sessionId = sessionIdOf(exec);
+		if (sessionId === void 0) return;
+		service.noteSessionWrite(sessionId);
+		const current = bindingOf(exec);
+		if (current !== void 0 && (current.projectId !== binding.projectId || current.resourceId !== void 0)) return;
+		if (current !== void 0 && binding.resourceId === void 0) return;
+		await service.setBinding(sessionId, binding);
+	};
+	/** The textbooks of the bound project, as one teaching line for a refusal. */
+	const textbookList = (exec) => {
+		const textbooks = (sessionIdOf(exec) === void 0 ? void 0 : service.bindingSummary(sessionIdOf(exec), 0))?.textbooks ?? [];
+		return textbooks.length === 0 ? "" : ` — this project's textbooks: ${textbooks.map((textbook) => `${textbook.seq ?? "-"}. ${textbook.id} 《${textbook.title}》`).join("; ")}`;
+	};
+	/** The resource: the argument (either spelling), else the binding's resource, else a lesson. */
+	const resourceOf = (args, exec) => {
+		const named = pickString(args.resource, args.book);
+		if (named !== void 0) return named;
+		const bound = bindingOf(exec)?.resourceId;
+		if (bound !== void 0) return bound;
+		throw new Error(`no textbook named: pass resource${textbookList(exec) || " (library_read · resources lists them)"}, or bind this session to one (library_binding)`);
+	};
+	/** The shared scope parameters (write tools). */
+	const scopeParams = { project: {
+		type: "string",
+		description: "Defaults to the binding."
+	} };
+	return {
+		service,
+		images,
+		bindingOf,
+		projectOf,
+		autoBind,
+		textbookList,
+		resourceOf,
+		scopeParams,
+		textbookParams: {
+			...scopeParams,
+			resource: {
+				type: "string",
+				description: "Defaults to the binding."
+			}
+		}
+	};
+}
+//#endregion
+//#region lib/types/tools/read.js
+/**
+* The `library_read` tool (moved verbatim from tool-definition.ts; the shared
+* helpers and schemas are in `tools/kit.ts`).
+*
+* @module @khorsheed/dsh-library/tools/read
+*/
+/**
+* A path as the coach needs it: each station's id, title, state, rows and
+* points, and whether its 讲义 exist — never the 讲义 text itself (a read of
+* an 11-station path once returned 7,300 characters).
+*/
+function compactRoadmap(read) {
+	const stations = (roadmap) => roadmap.nodes.map((node) => ({
+		id: node.id,
+		title: node.title,
+		state: node.state,
+		...node.gate === "quiz" ? {} : { gate: node.gate },
+		rows: node.covers.flatMap((cover) => cover.locator === void 0 ? [] : [cover.locator]).join(",") || void 0,
+		points: (node.points ?? []).map((point) => `${point.id}: ${point.title}`),
+		...node.goals.length === 0 ? {} : { goals: node.goals },
+		...node.acceptance === void 0 || node.acceptance.length === 0 ? {} : { acceptance: node.acceptance },
+		...node.notes === void 0 ? {} : { notes: `${node.notes.text.length} chars, revision ${node.notes.revisions}` },
+		...node.quizStats === void 0 ? {} : { best: node.quizStats.bestRatio }
+	}));
+	return {
+		...read.roadmap === void 0 ? { adopted: null } : { adopted: { stations: stations(read.roadmap) } },
+		...read.draft === void 0 ? {} : { draft: {
+			stations: stations(read.draft),
+			note: read.draft.note
+		} }
+	};
+}
+/** Build the `library_read` tool over the shared kit. */
+function libraryReadTool(kit) {
+	const { service, bindingOf, projectOf, resourceOf } = kit;
+	return defineTool({
+		name: "library_read",
+		description: "Read the library: projects (all, with this session's binding) | resources (one project's textbooks in study order) | toc (a textbook's contents rows) | roadmap (a textbook's path and pending draft) | pages (photographed pages) | cards (the learner's cards, weakest first) | quiz (one quiz, or the list). project and resource default to the binding.",
+		parameters: {
+			what: {
+				type: "string",
+				description: "One of the reads above."
+			},
+			project: { type: "string" },
+			resource: { type: "string" },
+			node: {
+				type: "string",
+				description: "A station (pages / cards)."
+			},
+			quiz: {
+				type: "string",
+				description: "A quiz id."
+			},
+			query: {
+				type: "string",
+				description: "cards: search term, gloss, sentences."
+			},
+			due: {
+				type: "boolean",
+				description: "cards: only those due for review."
+			}
+		},
+		output: jsonOutput(),
+		isConcurrencySafe: () => true,
+		async execute(args, exec) {
+			const argsAny = args;
+			switch (typeof args.what === "string" && args.what !== "" ? args.what : args.quiz !== void 0 ? "quiz" : args.resource !== void 0 || args.node !== void 0 ? "roadmap" : "projects") {
+				case "projects": return {
+					...await service.listProjects(),
+					binding: bindingOf(exec) ?? null
+				};
+				case "resources":
+				case "books": {
+					const detail = unwrap(await service.getProject({ id: projectOf(args.project, exec) }));
+					return {
+						project: detail.project,
+						resources: detail.resources
+					};
+				}
+				case "toc": {
+					const resource = resourceOf(args, exec);
+					return unwrap(await service.getResource({
+						projectId: projectOf(args.project, exec, resource),
+						resourceId: resource
+					})).resource;
+				}
+				case "roadmap": {
+					const resource = resourceOf(args, exec);
+					return compactRoadmap(await service.getRoadmap({
+						projectId: projectOf(args.project, exec, resource),
+						resourceId: resource
+					}));
+				}
+				case "pages": {
+					const resource = resourceOf(args, exec);
+					return await service.listPages({
+						projectId: projectOf(args.project, exec, resource),
+						resourceId: resource,
+						...args.node === void 0 ? {} : { nodeId: args.node }
+					});
+				}
+				case "cards": {
+					const resource = pickString(args.resource, args.book);
+					const result = await service.listCards({
+						projectId: projectOf(args.project, exec, resource),
+						...resource === void 0 ? {} : { resourceId: resource },
+						...args.node === void 0 ? {} : { nodeId: args.node },
+						...args.query === void 0 ? {} : { query: args.query },
+						...argsAny.kind === "word" || argsAny.kind === "concept" ? { kind: argsAny.kind } : {},
+						...[
+							"photo",
+							"chat",
+							"quiz",
+							"manual"
+						].includes(String(argsAny.source ?? "")) ? { source: argsAny.source } : {},
+						...typeof argsAny.weakMin === "number" ? { weakMin: argsAny.weakMin } : {},
+						...args.due === true ? { due: true } : {},
+						limit: typeof argsAny.limit === "number" ? argsAny.limit : 30
+					});
+					return {
+						total: result.total,
+						cards: result.cards.map((card) => ({
+							id: card.id,
+							kind: card.kind,
+							term: card.term,
+							...card.aliases.length === 0 ? {} : { aliases: card.aliases },
+							gloss: card.gloss,
+							...card.userGloss === void 0 ? {} : { userGloss: card.userGloss },
+							...card.resourceId === void 0 ? {} : { resource: card.resourceId },
+							contexts: card.contexts.slice(0, 2).map((context) => context.sentence),
+							weakness: card.weakness,
+							box: card.mastery.box,
+							dueAt: card.mastery.dueAt,
+							sources: card.sources.map((source) => source.note === void 0 ? source.type : `${source.type}: ${source.note}`).slice(-4)
+						}))
+					};
+				}
+				case "quiz": {
+					const resource = pickString(args.resource, args.book) ?? bindingOf(exec)?.resourceId;
+					const project = projectOf(args.project, exec, resource);
+					if (args.quiz === void 0 || args.quiz.trim() === "") return await service.listAssessments({
+						projectId: project,
+						type: "quiz",
+						...resource === void 0 ? {} : { resourceId: resource }
+					});
+					return unwrap(await service.getAssessment({
+						projectId: project,
+						assessmentId: args.quiz.trim()
+					})).assessment;
+				}
+				case "stats": return await service.stats();
+				default: throw new Error(`what is one of ${READ_WHATS.join(" | ")} — got ${JSON.stringify(args.what)}`);
+			}
+		}
+	});
+}
+//#endregion
+//#region lib/types/tools/project.js
+/**
+* The `library_project` tool (moved verbatim from tool-definition.ts; the shared
+* helpers and schemas are in `tools/kit.ts`).
+*
+* @module @khorsheed/dsh-library/tools/project
+*/
+/** Build the `library_project` tool over the shared kit. */
+function libraryProjectTool(kit) {
+	const { service, autoBind } = kit;
+	return defineTool({
+		name: "library_project",
+		description: "Create a learning project (one goal), or edit one (projectId + what changes; goal \"\" clears). template: subject | language (marks are words) | custom. Next: shelve its textbooks (library_textbook).",
+		parameters: {
+			projectId: {
+				type: "string",
+				description: "Edit this project; omit to create (ids are minted)."
+			},
+			name: { type: "string" },
+			template: {
+				type: "string",
+				enum: [
+					"subject",
+					"language",
+					"custom"
+				]
+			},
+			goal: {
+				type: "string",
+				description: "One line."
+			}
+		},
+		output: jsonOutput(),
+		isConcurrencySafe: () => false,
+		async execute(args, exec) {
+			const legacyId = args.id;
+			const editId = pickString(args.projectId, legacyId);
+			if (editId !== void 0) {
+				const patch = {};
+				if (typeof args.name === "string") patch.name = args.name;
+				if (typeof args.template === "string") patch.template = args.template;
+				if (typeof args.goal === "string") patch.goal = args.goal;
+				if (Object.keys(patch).length === 0) throw new Error("editing a project takes projectId plus the fields to change (name? / goal? / template?) — omit projectId to CREATE one (name + template)");
+				const edited = await service.updateProject({
+					id: editId,
+					patch
+				});
+				if (edited.ok) {
+					await autoBind(exec, { projectId: edited.project.id });
+					return edited;
+				}
+				if (typeof args.name !== "string" || args.name.trim() === "") throw new Error(edited.message);
+				const created = unwrap(await service.createProject({
+					name: args.name,
+					...typeof args.template === "string" ? { template: args.template } : {},
+					...typeof args.goal === "string" ? { goal: args.goal } : {}
+				}));
+				await autoBind(exec, { projectId: created.project.id });
+				return {
+					...created,
+					note: `no project ${JSON.stringify(editId)} existed — created a new one instead (ids are minted (p_…), never chosen by the caller; omit projectId to create)`
+				};
+			}
+			if (typeof args.name !== "string" || args.name.trim() === "") throw new Error("creating a project takes name (+ template: \"language\" | \"subject\" | \"custom\", goal?) — e.g. { name: \"数学\", template: \"subject\" }");
+			const created = unwrap(await service.createProject({
+				name: args.name,
+				...typeof args.template === "string" ? { template: args.template } : {},
+				...typeof args.goal === "string" ? { goal: args.goal } : {}
+			}));
+			await autoBind(exec, { projectId: created.project.id });
+			return created;
+		}
+	});
+}
+//#endregion
+//#region lib/types/tools/resource.js
+/**
+* The `library_textbook` tool (moved verbatim from tool-definition.ts; the shared
+* helpers and schemas are in `tools/kit.ts`).
+*
+* @module @khorsheed/dsh-library/tools/resource
+*/
+/** Build the `library_textbook` tool over the shared kit (the file keeps its v5 name). */
+function libraryResourceTool(kit) {
+	const { service, projectOf, autoBind, scopeParams } = kit;
+	return defineTool({
+		name: "library_textbook",
+		description: "Shelve, correct, reorder or remove a textbook (anything with a contents) — in study order. origin: learner (their own) | picked (a book or course you chose; its path takes only the chapters the goal needs) | authored (you write it: one chapter per lesson, your 讲义 are its text). A real book: verify the edition and contents online and cite the page (tocSource { by: \"web\", url }) — search the title with its author or ISBN, narrowed with site: to catalog or publisher pages (site:book.douban.com, site:worldcat.org, the publisher's domain), one query per edition to tell apart, never a \" in a query; never ask for an upload. A correction (resourceId) sends only what changes. A web page a station cites is no textbook — the path names its url.",
+		parameters: {
+			...scopeParams,
+			op: {
+				type: "string",
+				required: true,
+				description: "add | update | move | remove."
+			},
+			resourceId: {
+				type: "string",
+				description: "The textbook to update / move / remove."
+			},
+			title: {
+				type: "string",
+				description: "The exact edition's title."
+			},
+			origin: {
+				type: "string",
+				enum: [
+					"learner",
+					"picked",
+					"authored"
+				]
+			},
+			toc: {
+				type: "json",
+				description: "The contents: one chapter per line in one string, or [\"…\", \"…\"]."
+			},
+			tocSource: {
+				type: "json",
+				description: "{ by: \"web\" | \"model\" | \"photo\", url? } — web needs the url."
+			},
+			seq: {
+				type: "integer",
+				description: "Its place in the study order, from 1."
+			},
+			bookKind: {
+				type: "string",
+				enum: ["knowledge", "material"],
+				description: "material only when the exact text is what is tested (exam papers, literature)."
+			},
+			edition: { type: "string" },
+			author: { type: "string" },
+			url: {
+				type: "string",
+				description: "A digital textbook's home page."
+			},
+			note: {
+				type: "string",
+				description: "One line on why it is here."
+			}
+		},
+		output: jsonOutput(),
+		isConcurrencySafe: () => false,
+		async execute(args, exec) {
+			const argsAny = args;
+			const namedId = pickString(args.resourceId, argsAny.bookId);
+			const op = args.op === "add" || args.op === "update" ? "create" : args.op;
+			if (op === "remove") {
+				if (namedId === void 0) throw new Error("library_textbook · op=remove takes the resourceId field — library_read · resources lists the ids");
+				return unwrap(await service.removeResource({
+					projectId: projectOf(args.project, exec, namedId),
+					resourceId: namedId
+				}));
+			}
+			if (op === "move") {
+				if (namedId === void 0 || typeof args.seq !== "number") throw new Error("library_textbook · op=move takes resourceId and seq (the textbook's new place, from 1)");
+				return { order: unwrap(await service.moveResource({
+					projectId: projectOf(args.project, exec, namedId),
+					resourceId: namedId,
+					seq: args.seq
+				})).resources.filter((resource) => resource.seq !== void 0).map((resource) => `${resource.seq}. ${resource.id} 《${resource.title}》`) };
+			}
+			if (op !== "create") throw new Error(`library_textbook needs op: add | update | move | remove — got ${JSON.stringify(args.op)}`);
+			const originArg = argsAny.origin ?? (argsAny.addedBy === "learner" ? "learner" : argsAny.addedBy === "coach" ? "picked" : void 0);
+			const origin = originArg === "learner" || originArg === "picked" || originArg === "authored" ? { origin: originArg } : {};
+			const projectId = projectOf(args.project, exec, namedId);
+			const from = payload(argsAny.from);
+			if (from !== void 0) {
+				const fromProject = pickString(from.project, from.projectId);
+				const fromResource = pickString(from.resource, from.resourceId, from.book, from.bookId);
+				if (fromProject === void 0 || fromResource === void 0) throw new Error("from is { project, resource } — the OTHER project's id and the entry's id there");
+				const cloned = unwrap(await service.putResource({
+					projectId,
+					title: "",
+					kind: "article",
+					...namedId === void 0 ? {} : { resourceId: namedId },
+					from: {
+						projectId: fromProject,
+						resourceId: fromResource
+					}
+				}));
+				await autoBind(exec, {
+					projectId,
+					resourceId: cloned.resource.id
+				});
+				return cloned;
+			}
+			const tocList = payloadList(args.toc);
+			const sentRows = typeof args.toc === "string" && tocList === void 0 ? splitTocText(args.toc) : tocList ?? [];
+			const shelved = namedId !== void 0 && sentRows.length === 0 && pickString(args.url) === void 0 ? await service.getResource({
+				projectId,
+				resourceId: namedId
+			}) : void 0;
+			const kept = shelved?.ok === true && isThickResource(shelved.resource) ? shelved.resource : void 0;
+			const tocRows = sentRows.length > 0 ? sentRows : (kept?.toc ?? []).map((entry) => ({ ...entry }));
+			if (kept !== void 0) {
+				if (typeof args.title !== "string" || args.title.trim() === "") argsAny.title = kept.title;
+				if (argsAny.kind === void 0) argsAny.kind = kept.kind;
+			}
+			const linkKind = typeof argsAny.kind === "string" && argsAny.kind !== "book" && argsAny.kind !== "course" && LIBRARY_RESOURCE_KINDS.includes(argsAny.kind);
+			if (tocRows.length > 0 || !linkKind) {
+				if (typeof args.title !== "string" || args.title.trim() === "" || tocRows.length === 0) throw new Error(`a textbook takes: title, toc (one chapter per line), tocSource { by, url? }, origin (+ seq?, bookKind?, edition?, author?; resourceId to update one) — ${arrival("toc", args.toc)}`);
+				const toc = tocRows.map((row) => typeof row === "string" ? { title: row } : row);
+				const written = unwrap(await service.putResource({
+					projectId,
+					...namedId === void 0 ? {} : { resourceId: namedId },
+					title: args.title,
+					kind: argsAny.kind === "course" ? "course" : "book",
+					...typeof args.url === "string" ? { url: args.url } : {},
+					...typeof args.note === "string" ? { note: args.note } : {},
+					...origin,
+					...typeof args.seq === "number" ? { seq: args.seq } : {},
+					toc,
+					tocSource: payload(args.tocSource) ?? kept?.tocSource ?? { by: "model" },
+					...args.bookKind === "knowledge" || args.bookKind === "material" ? { bookKind: args.bookKind } : {},
+					...typeof argsAny.short === "string" ? { short: argsAny.short } : {},
+					...typeof args.author === "string" ? { author: args.author } : {},
+					...typeof args.edition === "string" ? { edition: args.edition } : {},
+					...typeof argsAny.isbn === "string" ? { isbn: argsAny.isbn } : {},
+					...Array.isArray(payloadList(argsAny.extras)) ? { extras: payloadList(argsAny.extras) } : {}
+				}));
+				await autoBind(exec, {
+					projectId,
+					resourceId: written.resource.id
+				});
+				const rows = written.resource.toc?.length ?? 0;
+				return {
+					...written,
+					contentsRows: rows,
+					...rows < 3 ? { warning: `the contents has only ${rows} row(s) — one row per chapter is expected (station chapters count these rows). If the chapters got joined, resend toc with one chapter per line and resourceId ${written.resource.id}` } : {}
+				};
+			}
+			const title = pickString(args.title);
+			const url = pickString(args.url);
+			if (title === void 0 || url === void 0) throw new Error(`a link takes: title, url, kind ("article"|"video"|"repo"|"tool"|"hardware"), note? — got title ${title === void 0 ? "✗ MISSING" : "✓"} · url ${url === void 0 ? "✗ MISSING" : "✓"} (a textbook takes kind "book" | "course" + toc)`);
+			const added = unwrap(await service.putResource({
+				projectId,
+				...namedId === void 0 ? {} : { resourceId: namedId },
+				title,
+				kind: linkKind ? argsAny.kind : "article",
+				url,
+				...typeof args.note === "string" ? { note: args.note } : {},
+				...origin
+			}));
+			await autoBind(exec, { projectId });
+			return added;
+		}
+	});
+}
+//#endregion
+//#region lib/types/tools/roadmap.js
+/**
+* The `library_roadmap` tool (moved verbatim from tool-definition.ts; the shared
+* helpers and schemas are in `tools/kit.ts`).
+*
+* @module @khorsheed/dsh-library/tools/roadmap
+*/
+/** Build the `library_roadmap` tool over the shared kit. */
+function libraryRoadmapTool(kit) {
+	const { service, projectOf, autoBind, textbookList } = kit;
+	return defineTool({
+		name: "library_roadmap",
+		description: "Draft one textbook's path (replaces its previous draft); the learner adopts it in the sidebar. One station = one lesson: 3–5 knowledge points, simple → hard. A real book's long chapter splits into several stations; a textbook you authored teaches one chapter per station.",
+		parameters: {
+			resource: {
+				type: "string",
+				required: true,
+				description: "The textbook."
+			},
+			nodes: {
+				...NODES_SCHEMA,
+				required: true,
+				description: "The stations, in study order."
+			},
+			note: {
+				type: "string",
+				description: "One line of pacing for the draft card."
+			}
+		},
+		output: jsonOutput(),
+		isConcurrencySafe: () => false,
+		async execute(args, exec) {
+			const list = payloadList(args.nodes);
+			if (list === void 0) throw new Error(`library_roadmap takes resource and nodes: [{ id, title, chapters: "3-4", points: [{ id, title }] (3–5), goals?, acceptance? }] — ${arrival("nodes", args.nodes)}`);
+			const argsAny = args;
+			const resourceId = pickString(args.resource, argsAny.book);
+			if (resourceId === void 0) throw new Error(`a path belongs to one textbook — pass resource${textbookList(exec) || " (shelve the textbook first with library_textbook)"}`);
+			const adjusted = [];
+			const missingPoints = [];
+			const nodes = list.map((node) => {
+				const { chapters, also, chapterRanges, covers, kind, gate, points, ...rest } = node;
+				const gateValue = typeof gate === "string" ? gate : kind === "practice" ? "acceptance" : typeof kind === "string" ? kind : "quiz";
+				if (gateValue === "quiz" && Array.isArray(rest.acceptance) && rest.acceptance.length > 0) {
+					const lines = rest.acceptance.flatMap((line) => typeof line === "string" ? [line] : typeof payload(line)?.line === "string" ? [String(payload(line).line)] : []);
+					rest.goals = [...Array.isArray(rest.goals) ? rest.goals : typeof rest.goals === "string" ? [rest.goals] : [], ...lines];
+					delete rest.acceptance;
+				}
+				if (gateValue === "quiz" && (!Array.isArray(points) || points.length === 0)) missingPoints.push(String(rest.id ?? rest.title ?? "?"));
+				const keepPoints = gateValue === "quiz" || points === void 0 || Array.isArray(points) && points.length === 0;
+				if (!keepPoints) adjusted.push(`points dropped on ${String(rest.title ?? rest.id)} — a ${String(gateValue)} station has no quiz; what it checks belongs in ${gateValue === "acceptance" ? "acceptance lines" : "goals"}`);
+				const main = [];
+				const spelled = typeof chapters === "string" && chapters.trim() !== "" ? chaptersLocator(chapters) : void 0;
+				if (spelled?.rest !== void 0) adjusted.push(`${String(rest.title ?? rest.id)}: "${spelled.rest}" in chapters is not a row number — kept as a side reference (topic: ${spelled.rest})`);
+				const locator = typeof chapters === "number" ? String(chapters) : spelled !== void 0 ? spelled.locator : Array.isArray(chapters) ? chapters.filter((entry) => typeof entry === "number" || typeof entry === "string").join(",") : Array.isArray(chapterRanges) ? formatLocator(chapterRanges.flatMap((range) => {
+					const row = payload(range);
+					return typeof row?.from === "number" && typeof row.to === "number" ? [{
+						from: row.from,
+						to: row.to
+					}] : [];
+				})) : void 0;
+				if (locator !== void 0 && locator !== "") main.push({
+					ref: resourceId,
+					locator
+				});
+				const side = [
+					...Array.isArray(covers) ? covers : [],
+					...Array.isArray(also) ? also : typeof also === "string" ? [also] : [],
+					...spelled?.rest === void 0 ? [] : [`topic: ${spelled.rest}`]
+				].map((cover) => normalizeCoverArg(cover) ?? cover);
+				const all = main.length === 0 && side.length === 0 ? [{ ref: resourceId }] : [...main, ...side];
+				return {
+					...rest,
+					...gateValue === void 0 ? {} : { gate: gateValue },
+					...keepPoints && points !== void 0 ? { points } : {},
+					covers: all
+				};
+			});
+			if (missingPoints.length > 0) throw new Error(`every station needs its 3–5 knowledge points (points: [{ id, title }]) — the chapter quiz asks them: ${missingPoints.join(", ")}`);
+			const projectId = projectOf(argsAny.project, exec, resourceId);
+			const replaced = unwrap(await service.getProject({ id: projectId })).project.resources.find((row) => row.id === resourceId)?.hasDraft === true;
+			const drafted = unwrap(await service.draftRoadmap({
+				projectId,
+				resourceId,
+				nodes,
+				...typeof argsAny.passRatio === "number" ? { passRatio: argsAny.passRatio } : {},
+				...typeof args.note === "string" ? { note: args.note } : {}
+			}));
+			await autoBind(exec, {
+				projectId,
+				resourceId
+			});
+			const after = unwrap(await service.getProject({ id: projectId }));
+			const textbook = after.project.resources.find((row) => row.id === resourceId);
+			return {
+				ok: true,
+				placedOn: `${textbook?.seq ?? "-"}. 《${textbook?.title ?? resourceId}》 (${resourceId})`,
+				stations: drafted.draft.nodes.length,
+				...replaced ? { replacedDraft: true } : {},
+				waitingForAdoption: after.project.resources.filter((row) => row.hasDraft).map((row) => `${row.seq ?? "-"}. 《${row.title}》 ${row.draftTotal ?? 0} stations`),
+				...adjusted.length === 0 ? {} : { adjusted },
+				next: "Describe the path to the learner in two lines and ask them to review and adopt it in the sidebar (采用). Then stop: before they adopt it, write no 讲义, teach nothing, set no quiz."
+			};
+		}
+	});
+}
+//#endregion
+//#region lib/types/tools/notes.js
+/**
+* The `library_notes` tool (moved verbatim from tool-definition.ts; the shared
+* helpers and schemas are in `tools/kit.ts`).
+*
+* @module @khorsheed/dsh-library/tools/notes
+*/
+/** Build the `library_notes` tool over the shared kit. */
+function libraryNotesTool(kit) {
+	const { service, projectOf, resourceOf, textbookParams } = kit;
+	return defineTool({
+		name: "library_notes",
+		description: "Write or rewrite a station's 讲义 (markdown, math in $…$), for THIS learner, when they start the station. The 讲义 are the lesson itself — the learner learns from them without leaving the page, whatever the textbook: open with the core question and 「你将学到」 (the points, numbered) and one or two warm-up questions; then one ## section per knowledge point, headed by its title — explain it plainly, give a concrete example or the steps to try, a common mistake, and a 思考题; then 小结. Outside material (a manual page, a video, the learner's book pages) goes only in a final ## 参考 section, never as the lesson. No change logs or internal words.",
+		parameters: {
+			...textbookParams,
+			node: {
+				type: "string",
+				required: true,
+				description: "The station id."
+			},
+			text: {
+				type: "string",
+				required: true,
+				description: "The 讲义, markdown."
+			}
+		},
+		output: jsonOutput(),
+		isConcurrencySafe: () => false,
+		async execute(args, exec) {
+			const resourceId = resourceOf(args, exec);
+			const written = unwrap(await service.putNotes({
+				projectId: projectOf(args.project, exec, resourceId),
+				resourceId,
+				nodeId: String(args.node),
+				text: String(args.text)
+			}));
+			return {
+				...written,
+				next: written.notes.revisions === 1 ? "Tell the learner in one line that the 讲义 are ready in the sidebar, then wait — they read first and ask." : "Tell the learner in one line what changed in the 讲义."
+			};
+		}
+	});
+}
+//#endregion
+//#region lib/types/tools/page.js
+/**
+* The `library_page` tool (moved verbatim from tool-definition.ts; the shared
+* helpers and schemas are in `tools/kit.ts`).
+*
+* @module @khorsheed/dsh-library/tools/page
+*/
+/** Build the `library_page` tool over the shared kit. */
+function libraryPageTool(kit) {
+	const { service, images, projectOf, resourceOf, textbookParams } = kit;
+	return defineTool({
+		name: "library_page",
+		description: "Record a photographed page in one call: its printed text and every mark the learner made (each certain mark becomes a card). Omit attachment for the latest photo. If you cannot see images, say so instead.",
+		parameters: {
+			...textbookParams,
+			text: {
+				type: "string",
+				required: true,
+				description: "The printed text."
+			},
+			marks: {
+				oneOf: [{
+					type: "array",
+					items: {
+						type: "object",
+						additionalProperties: true,
+						properties: {
+							text: {
+								type: "string",
+								description: "As printed."
+							},
+							sentence: { type: "string" },
+							handNote: {
+								type: "string",
+								description: "The learner's handwriting beside it."
+							},
+							gloss: {
+								type: "string",
+								description: "In-context meaning."
+							},
+							uncertain: {
+								type: "boolean",
+								description: "You could not tell (kept, not carded)."
+							}
+						}
+					}
+				}, {
+					type: "string",
+					description: "The same list as JSON text."
+				}],
+				required: true,
+				description: "Every mark on the page."
+			},
+			attachment: {
+				type: "string",
+				description: "The image id (omit for the latest photo in this conversation)."
+			},
+			label: {
+				type: "string",
+				description: "What the learner calls the page (「p.16」)."
+			},
+			node: {
+				type: "string",
+				description: "The station id, when the page belongs to one."
+			}
+		},
+		output: jsonOutput(),
+		isConcurrencySafe: () => false,
+		async execute(args, exec) {
+			const marks = payloadList(args.marks);
+			if (marks === void 0) throw new Error(`library_page takes: text (the page's printed text), marks: [{ text, sentence?, handNote?, gloss?, uncertain? }] (+ attachment?, label?, node?) — ${arrival("marks", args.marks)}`);
+			const attachment = images.resolve(sessionIdOf(exec), typeof args.attachment === "string" ? args.attachment : void 0);
+			if (attachment === void 0) throw new Error("no photo to record: this conversation has no image the library saw arrive (or the id names none) — ask the learner to send the page photo here, then record it");
+			const pageResource = resourceOf(args, exec);
+			return unwrap(await service.recordPage({
+				projectId: projectOf(args.project, exec, pageResource),
+				resourceId: pageResource,
+				...typeof args.node === "string" && args.node !== "" ? { nodeId: args.node } : {},
+				...typeof args.label === "string" ? { label: args.label } : {},
+				attachment,
+				text: args.text,
+				marks
+			}));
+		}
+	});
+}
+//#endregion
+//#region lib/types/tools/cards.js
+/**
+* The `library_cards` tool (moved verbatim from tool-definition.ts; the shared
+* helpers and schemas are in `tools/kit.ts`).
+*
+* @module @khorsheed/dsh-library/tools/cards
+*/
+/** Build the `library_cards` tool over the shared kit. */
+function libraryCardsTool(kit) {
+	const { service, bindingOf, projectOf, scopeParams } = kit;
+	return defineTool({
+		name: "library_cards",
+		description: "The learner is stuck on the material (mixes it up, asks the same thing again) → note it now, then say in one line what you noted. Subject projects: { point, gloss } — the note lands on the current station's knowledge point. Language projects: { term, gloss, sentence? } becomes a word card; a near-duplicate comes back pending — resend it with mergeInto or asNew. Not a weak point: curiosity, your own slip (fix the quiz), or feedback on a question or the tools.",
+		parameters: {
+			...scopeParams,
+			resource: {
+				type: "string",
+				description: "The textbook (defaults to the binding's)."
+			},
+			cards: {
+				oneOf: [{
+					type: "array",
+					items: {
+						type: "object",
+						additionalProperties: true,
+						properties: {
+							point: {
+								type: "string",
+								description: "Subject: the knowledge point id."
+							},
+							term: {
+								type: "string",
+								description: "What they stuck on, in a few words."
+							},
+							gloss: {
+								type: "string",
+								description: "What they got wrong, or the meaning."
+							},
+							sentence: {
+								type: "string",
+								description: "Language: the sentence it came from."
+							},
+							mergeInto: { type: "string" },
+							asNew: { type: "boolean" }
+						}
+					}
+				}, {
+					type: "string",
+					description: "The same list as JSON text."
+				}],
+				required: true
+			}
+		},
+		output: jsonOutput(),
+		isConcurrencySafe: () => false,
+		async execute(args, exec) {
+			const list = payloadList(args.cards);
+			if (list === void 0) throw new Error(`library_cards takes cards: [{ point, gloss }] (subject) or [{ term, gloss, sentence? }] (language) — ${arrival("cards", args.cards)}`);
+			const sessionId = sessionIdOf(exec);
+			const resource = pickString(args.resource, args.book) ?? bindingOf(exec)?.resourceId;
+			const projectId = projectOf(args.project, exec, resource);
+			const project = profileOf(unwrap(await service.getProject({ id: projectId })).project.template);
+			const cards = list.map((card) => {
+				const source = payload(card.source) ?? { type: "chat" };
+				const context = payload(card.context) ?? (pickString(card.sentence) === void 0 ? void 0 : { sentence: card.sentence });
+				return {
+					...card,
+					kind: card.kind === "word" || card.kind === "concept" ? card.kind : project.markKind,
+					...card.weaken === void 0 && source.type === "chat" ? { weaken: true } : {},
+					source: {
+						...source,
+						...source.type === "chat" && source.ref === void 0 && sessionId !== void 0 ? { ref: sessionId } : {}
+					},
+					...context === void 0 ? {} : { context: {
+						sentence: String(context.sentence ?? ""),
+						...typeof context.node === "string" ? { nodeId: context.node } : {}
+					} }
+				};
+			});
+			const pointed = project.pointsDriven ? list.filter((card) => pickString(card.point) !== void 0) : [];
+			const noted = [];
+			for (const card of pointed) {
+				const station = pickString(card.node, payload(card.context)?.node) ?? (sessionId === void 0 ? void 0 : service.bindingSummary(sessionId, 0).station?.id);
+				if (station === void 0) throw new Error("a point note needs its station: node (the per-turn context names the current station and its points)");
+				const term = pickString(card.term);
+				const text = [term, pickString(card.gloss, card.userGloss)].filter(Boolean).join(" — ");
+				const written = unwrap(await service.notePoint({
+					projectId,
+					...resource === void 0 ? {} : { resourceId: resource },
+					nodeId: station,
+					pointId: pickString(card.point),
+					text: text === "" ? String(card.gloss ?? "") : text,
+					...term === void 0 ? {} : { term },
+					...sessionId === void 0 ? {} : { session: sessionId }
+				}));
+				noted.push({
+					point: written.point.title,
+					state: written.point.state,
+					...written.changes.length === 0 ? {} : { changed: written.changes.map((change) => `${change.title}: ${change.from} → ${change.to}`) }
+				});
+			}
+			const rest = cards.filter((_card, index) => !pointed.includes(list[index]));
+			if (project.pointsDriven) {
+				const loose = rest.filter((card) => card.source?.type === "chat");
+				if (loose.length > 0) {
+					const points = sessionId === void 0 ? [] : service.bindingSummary(sessionId, 0).station?.mastery.points ?? [];
+					throw new Error(`in a subject project a weak point from the conversation lands on the station's knowledge point — add point (+ node) to: ${loose.map((card) => card.term ?? "?").join(", ")}${points.length === 0 ? "" : `; this station's points: ${points.map((point) => `${point.id} (${point.title})`).join(", ")}`}. Record only what the LEARNER got wrong about the material — never your own slip (a wrong answer key: fix the quiz) and never feedback on a question or the tools. If none of that applies, record nothing.`);
+				}
+			}
+			return {
+				...(rest.length === 0 ? void 0 : unwrap(await service.writeCards({
+					projectId,
+					...resource === void 0 ? {} : { resourceId: resource },
+					cards: rest
+				}))) ?? { ok: true },
+				...noted.length === 0 ? {} : { pointNotes: noted }
+			};
+		}
+	});
+}
+//#endregion
+//#region lib/types/tools/quiz.js
+/**
+* The `library_quiz` tool (moved verbatim from tool-definition.ts; the shared
+* helpers and schemas are in `tools/kit.ts`).
+*
+* @module @khorsheed/dsh-library/tools/quiz
+*/
+/** Build the `library_quiz` tool over the shared kit. */
+function libraryQuizTool(kit) {
+	const { service, bindingOf, projectOf, autoBind, scopeParams } = kit;
+	return defineTool({
+		name: "library_quiz",
+		description: "Store a quiz, then reply with one line — the learner answers in the sidebar. node = the station it tests (omit: a whole-textbook quiz; resource null: a free quiz). focus is the learner's choice: mine = only their cards; book = the chapter only; mixed = their cards, then the chapter. Every question names its point; quiz weak and untested points first, then practicing ones. Solve each question again before storing; fix any disagreement. choice: answer = the right option verbatim. fill: a short value (1/2), several blanks comma-separated, alternatives \" / \". free: say what a good answer covers. Math only in $…$. The prompt carries no kind label or chapter reference. A material textbook needs quote (the page text). Replace voided (「这题有问题」) questions on the same points.",
+		parameters: {
+			...scopeParams,
+			resource: {
+				type: "json",
+				description: "The textbook (defaults to the binding's); null = a free quiz."
+			},
+			node: {
+				type: "string",
+				description: "The quiz-gated station it gates."
+			},
+			focus: {
+				type: "string",
+				enum: [
+					"mine",
+					"book",
+					"mixed"
+				]
+			},
+			questions: {
+				...QUESTIONS_SCHEMA,
+				required: true,
+				description: "The questions."
+			}
+		},
+		output: jsonOutput(),
+		isConcurrencySafe: () => false,
+		async execute(args, exec) {
+			const questions = payloadList(args.questions);
+			if (questions === void 0) throw new Error(`library_quiz takes questions: [{ point, kind: "choice"|"fill"|"free", prompt, options?, answer, explanation?, quote? }] (+ node?, focus?) — ${arrival("questions", args.questions)}`);
+			const node = typeof args.node === "string" && args.node !== "" ? args.node : void 0;
+			const argsAny = args;
+			const resourceId = args.resource === null || argsAny.book === null ? void 0 : pickString(args.resource, argsAny.book) ?? bindingOf(exec)?.resourceId;
+			const cleaned = questions.map((raw, index) => {
+				const text = (value) => typeof value === "string" ? value : typeof value === "number" ? String(value) : "";
+				let next = {
+					...raw,
+					id: text(raw.id) === "" ? `q${index + 1}` : text(raw.id),
+					kind: text(raw.kind),
+					prompt: text(raw.prompt),
+					answer: text(raw.answer)
+				};
+				if (next.options !== void 0) {
+					const options = normalizeQuizOptions(next.options);
+					if (options !== void 0) next = {
+						...next,
+						options
+					};
+				}
+				return normalizeQuestionAxes(next);
+			});
+			const projectId = projectOf(args.project, exec, resourceId);
+			const written = unwrap(await service.putQuiz({
+				projectId,
+				quiz: {
+					...args.focus === "mine" || args.focus === "book" || args.focus === "mixed" ? { focus: args.focus } : {},
+					scope: {
+						...resourceId === void 0 ? {} : { resourceId },
+						...node === void 0 ? {} : { nodeId: node }
+					},
+					questions: cleaned,
+					...Array.isArray(argsAny.addPoints) ? { addPoints: argsAny.addPoints } : {}
+				}
+			}));
+			await autoBind(exec, {
+				projectId,
+				...resourceId === void 0 ? {} : { resourceId }
+			});
+			return written;
+		}
+	});
+}
+//#endregion
+//#region lib/types/tools/binding.js
+/**
+* The `library_binding` tool (moved verbatim from tool-definition.ts; the shared
+* helpers and schemas are in `tools/kit.ts`).
+*
+* @module @khorsheed/dsh-library/tools/binding
+*/
+/** Build the `library_binding` tool over the shared kit. */
+function libraryBindingTool(kit) {
+	const { service, textbookList } = kit;
+	return defineTool({
+		name: "library_binding",
+		description: "Bind this session to a project (and optionally a textbook) — every tool's default. Writes bind an unbound session by themselves; use this to switch, or unbind: true.",
+		parameters: {
+			project: { type: "string" },
+			resource: {
+				type: "string",
+				description: "A textbook in it."
+			},
+			unbind: { type: "boolean" }
+		},
+		output: jsonOutput(),
+		isConcurrencySafe: () => false,
+		async execute(args, exec) {
+			const sessionId = sessionIdOf(exec);
+			if (sessionId === void 0) throw new Error("binding needs a session — this call came from none");
+			const argsAny = args;
+			if (args.unbind === true || argsAny.binding === null) return unwrap(await service.setBinding(sessionId, null));
+			const body = payload(argsAny.binding) ?? {};
+			const projectId = pickString(body.project, body.projectId, args.project);
+			const resourceId = pickString(body.resource, body.resourceId, body.book, body.bookId, args.resource, args.book);
+			if (projectId === void 0) throw new Error("binding needs the project: { project, resource? } (library_read · projects lists them); unbind: true to unbind");
+			if (resourceId !== void 0 && !(await service.getResource({
+				projectId,
+				resourceId
+			})).ok) return {
+				...unwrap(await service.setBinding(sessionId, { projectId })),
+				note: `no resource ${JSON.stringify(resourceId)} in this project — bound the project only. Resource ids are minted (r_…); registering the textbook (library_textbook) binds this session to it by itself${textbookList(exec)}`
+			};
+			return unwrap(await service.setBinding(sessionId, {
+				projectId,
+				...resourceId === void 0 ? {} : { resourceId }
+			}));
+		}
+	});
+}
+//#endregion
+//#region lib/types/tools/assess.js
+/**
+* The `library_assess` tool (moved verbatim from tool-definition.ts; the shared
+* helpers and schemas are in `tools/kit.ts`).
+*
+* @module @khorsheed/dsh-library/tools/assess
+*/
+/** A passed station's result carries the next step: name what follows and ask (the learner starts it). */
+function withNext(result) {
+	if (result.completed === void 0) return result;
+	return {
+		...result,
+		next: `Congratulate the learner, name the next station${result.unlocked !== void 0 && result.unlocked.length > 0 ? ` (${result.unlocked.join(", ")})` : ""} and ask whether to start it — start only when they say so.`
+	};
+}
+/** Build the `library_assess` tool over the shared kit. */
+function libraryAssessTool(kit) {
+	const { service, projectOf } = kit;
+	return defineTool({
+		name: "library_assess",
+		description: "Record a graded sitting after judging it in the chat: one verdict per question. The stored answer can be wrong — judge by the question, and say so when it was. A hands-on station: pass node instead of quiz; each task is a line id (L1, L2…). Then tell the learner what moved and what unlocked.",
+		parameters: {
+			project: {
+				type: "string",
+				description: "Project id (defaults to the binding)."
+			},
+			quiz: {
+				type: "string",
+				description: "The quiz id."
+			},
+			node: {
+				type: "string",
+				description: "A hands-on station, instead of quiz."
+			},
+			resource: {
+				type: "string",
+				description: "Its textbook (defaults to wherever the node is)."
+			},
+			verdicts: {
+				type: "array",
+				required: true,
+				items: {
+					type: "object",
+					additionalProperties: true,
+					properties: {
+						task: {
+							type: "string",
+							description: "The question id, or the line id (L1…)."
+						},
+						pass: { type: "boolean" },
+						ratio: {
+							type: "number",
+							description: "Partial credit 0..1."
+						},
+						why: {
+							type: "string",
+							description: "One line on the judgment."
+						},
+						void: {
+							type: "boolean",
+							description: "The learner flagged it broken."
+						},
+						missedCard: {
+							type: "object",
+							additionalProperties: false,
+							description: "Language projects: the word they missed.",
+							properties: {
+								term: { type: "string" },
+								gloss: { type: "string" }
+							}
+						}
+					}
+				}
+			}
+		},
+		output: jsonOutput(),
+		isConcurrencySafe: () => false,
+		async execute(args, exec) {
+			if (!Array.isArray(args.verdicts) || args.verdicts.length === 0) throw new Error("verdicts is required — one per question: [{ task: <question id>, pass, why, ratio?, void? }]");
+			const verdicts = args.verdicts.map((verdict) => {
+				const why = pickString(verdict.why, verdict.criterion, verdict.evidence) ?? "";
+				return {
+					...verdict,
+					criterion: pickString(verdict.criterion) ?? why,
+					evidence: pickString(verdict.evidence) ?? why,
+					by: verdict.by === "self" || verdict.by === "user" ? verdict.by : "llm"
+				};
+			});
+			const node = pickString(args.node);
+			if (node !== void 0) {
+				const resource = pickString(args.resource, args.book);
+				return withNext(unwrap(await service.putAttempt({
+					projectId: projectOf(args.project, exec, resource),
+					nodeId: node,
+					...resource === void 0 ? {} : { resourceId: resource },
+					verdicts
+				})));
+			}
+			const quiz = pickString(args.quiz);
+			if (quiz === void 0) throw new Error("quiz is the id library_quiz returned — or pass node (an acceptance station's id) for acceptance");
+			return withNext(unwrap(await service.putAttempt({
+				projectId: projectOf(args.project, exec),
+				assessmentId: quiz,
+				verdicts
+			})));
+		}
+	});
+}
+//#endregion
+//#region lib/types/tool-definition.js
+/** The names this module registers, in registration (workflow) order. */
+const LIBRARY_TOOL_NAMES = [
+	"library_read",
+	"library_project",
+	"library_textbook",
+	"library_roadmap",
+	"library_notes",
+	"library_page",
+	"library_cards",
+	"library_quiz",
+	"library_binding",
+	"library_assess"
+];
+/**
+* Build the tools. Creating them is the package's `./tool` row, which applies
+* the origin tag; this module never registers.
+* @param service - the library service the adapters translate to.
+* @param images - the session image references the tool row remembers (a
+*   page's photo is resolved from them, never trusted to the model's copy).
+* @returns the definitions, untagged and unregistered, in workflow order.
+*/
+function libraryToolDefinitions(service, images = new ImageRefCache()) {
+	const kit = createToolKit(service, images);
+	return [
+		libraryReadTool(kit),
+		libraryProjectTool(kit),
+		libraryResourceTool(kit),
+		libraryRoadmapTool(kit),
+		libraryNotesTool(kit),
+		libraryPageTool(kit),
+		libraryCardsTool(kit),
+		libraryQuizTool(kit),
+		libraryBindingTool(kit),
+		libraryAssessTool(kit)
+	];
+}
+//#endregion
+//#region lib/types/tool.js
+const PACKAGE_NAME = "@khorsheed/dsh-library";
+/**
+* Tag the model-visible tools with their origin (AGENTS.md § Tool origin
+* tagging; seam S12): the capability catalog reads this `Symbol.for`-keyed
+* tag back through `ctx.tools.get()`, so the library tools attribute to THIS
+* package (the row the preset mounts). The tag is host-side only and never
+* travels on the model wire. Inlined (the eval precedent) — importing the
+* helper from capability-catalog would be a cross-package edge.
+*/
+const definePluginTool = (def) => Object.assign(def, { [Symbol.for("dsh.tool.origin")]: {
+	channel: "plugin",
+	owner: PACKAGE_NAME
+} });
+const Config = z.object({
+	tools: z.union([z.const("all"), z.const("none")]).default("all"),
+	hideSections: z.array(z.string()).default([]),
+	denyTools: z.array(z.string()).default([])
+});
+/** Cordis plugin name used by loader diagnostics. */
+const name = "library-tool";
+/**
+* The `library` core is a declared inject (the owning-family companion
+* exception to the community-service probe rule): a preset's standing scope
+* mounts at registry-activation time, BEFORE the profile's later bundle rows
+* provide the core, so a one-shot ctx.get probe at apply saw ABSENT there and
+* nothing re-ran the row (rc.1 boot order; 3080 production 2026-09-27). The
+* declared inject pends the row until the core provides, then the body
+* applies. The tools registry and the prompt assembly still join through
+* deferred injection so their mount order cannot strand the registrations.
+*/
+const inject = ["library"];
+/**
+* The coach's guidance, registered beside the tools it describes (order 114,
+* the eval line). Per-`what` payloads are in the tool descriptions.
+*/
+const LIBRARY_PROMPT = `The library holds the learner's projects, textbooks, paths and quizzes — record them there, never only in the chat. A refusal says what to fix: fix it and resend. Quote with 「」 inside any text you pass.
+
+The learner leads; follow this order and stop where it says:
+1. A goal → ask one or two questions (level, direction), then library_project.
+2. Textbooks → library_textbook: the learner's book (verify edition and contents online), one you pick, or one you author.
+3. A path → library_roadmap. Then describe it in two lines and STOP: the learner reviews and adopts it in the sidebar. Before that: no 讲义, no teaching, no quiz.
+4. A station starts only when the learner says so (「开始学这一站」 or naming it). Then write its 讲义 for this learner (library_notes), say in one line that they are ready, and wait: the learner reads first and asks. Answer in the chat; if a question shows the 讲义 missed or got something wrong, fix that section.
+5. Stuck on the material → library_cards on that point. A quiz when asked → library_quiz, then one line. Grade → library_assess.
+6. A station passed → name the next one and ask whether to start it.
+
+The per-turn "Library:" context is the current state; trust it over the chat.`;
+/** The bound-context line's order: right after the sandbox / approval snapshots. */
+const CONTEXT_ORDER = 650;
+/** How many weak cards the per-turn context names. */
+const CONTEXT_CARDS = 12;
+/**
+* Render the per-turn context for one session: its binding and the weakest
+* cards there. Kept short — it rides every turn.
+*/
+function renderBindingContext(service, sessionId) {
+	const summary = service.bindingSummary(sessionId, CONTEXT_CARDS);
+	if (summary.binding === void 0) return "Library: this session is not bound to a project yet.";
+	if (summary.project === void 0) return "Library: this session's bound project no longer exists — ask the learner which one to use.";
+	const { project, resource, textbooks, weakCards } = summary;
+	const lines = [`Library: bound to project 「${project.name}」 (${project.id}, template ${project.template})` + (resource === void 0 ? "." : `, textbook 《${resource.title}》 (${resource.id}).`)];
+	if (summary.binding.previousProjectId !== void 0 && summary.binding.previousProjectId !== project.id) {
+		const previous = service.projectName(summary.binding.previousProjectId);
+		lines.push(`This session worked on another project${previous === void 0 ? "" : ` 「${previous}」`} before switching here: nothing said about it is 「${project.name}」's material — never quiz, teach or note from it here.`);
+	}
+	if (textbooks.length === 0) lines.push("Textbooks: none yet — shelve them first (library_textbook).");
+	else {
+		lines.push("Textbooks (study order):");
+		for (const textbook of textbooks) {
+			const state = textbook.roadmap === void 0 ? textbook.hasDraft ? `draft ${textbook.draftTotal ?? 0} stations, waiting for the learner to adopt` : "no path yet" : `path adopted, ${textbook.roadmap.done}/${textbook.roadmap.total} done` + (textbook.current === void 0 ? "" : `, current: ${textbook.current.title} (${textbook.current.id})`) + (textbook.hasDraft ? `; a new draft (${textbook.draftTotal ?? 0} stations) waits to replace it` : "");
+			lines.push(` ${textbook.seq ?? "-"}. 《${textbook.title}》 (${textbook.id}) ${state}`);
+		}
+	}
+	const profile = profileOf(project.template);
+	if (profile.pointsDriven && summary.station !== void 0) {
+		const { station } = summary;
+		lines.push(`Current station ${station.title} (${station.id}) — its points:`);
+		for (const point of station.mastery.points) {
+			const reason = masteryReason(point);
+			lines.push(` - ${point.title} (${point.id}): ${point.state}${reason === "" ? "" : ` — ${reason}`}`);
+		}
+		if (station.mastery.open.length > 0) lines.push(`Open misses here: ${station.mastery.open.length} (the learner retakes them in the sidebar; they count for points, not for passing).`);
+	}
+	if (weakCards.length > 0) lines.push(`Weak cards: ${weakCards.map((card) => `${card.term} [${card.weakness}]`).join("; ")}.`);
+	lines.push(`Subject: ${profile.coachHint}`);
+	return lines.join("\n");
+}
+/**
+* Plugin body: register the three tools, their guidance, and the per-turn
+* bound context; quiet the scope when configured. The declared `library`
+* inject pends the row until the core provides; the in-body guard stays as
+* the defensive direct-call path.
+* @param ctx - Cordis context (the preset's agent-plane mount).
+* @param config - validated plugin config.
+*/
+function apply(ctx, config = {}) {
+	const service = ctx.get("library");
+	if (service === void 0) {
+		ctx.logger.info(`${PACKAGE_NAME}: the global library service is absent — the library tools are not registered`);
+		return;
+	}
+	if ((config.tools ?? "all") === "none") return;
+	const images = new ImageRefCache();
+	ctx.on("session/event", ((session, event) => {
+		images.observe(String(session.id), event);
+	}));
+	ctx.inject(["tools"], (toolsCtx) => {
+		for (const definition of libraryToolDefinitions(service, images)) toolsCtx.effect(() => toolsCtx.tools.register(definePluginTool(definition)), `${PACKAGE_NAME}: ${definition.name} tool`);
+		for (const toolName of config.denyTools ?? []) try {
+			toolsCtx.effect(() => toolsCtx.tools.restrict({ deny: [toolName] }), `${PACKAGE_NAME}: mask ${toolName}`);
+		} catch (error) {
+			ctx.logger.info(`${PACKAGE_NAME}: could not mask ${toolName} here — ${error instanceof Error ? error.message : String(error)}`);
+		}
+	});
+	ctx.inject(["systemPrompt"], (promptCtx) => {
+		const prompt = promptCtx.get("systemPrompt");
+		if (prompt === void 0) return;
+		prompt.section({
+			name: "tool:library",
+			order: 114,
+			text: LIBRARY_PROMPT
+		});
+		for (const sectionName of config.hideSections ?? []) try {
+			prompt.section({
+				name: sectionName,
+				order: 0,
+				text: ""
+			});
+		} catch (error) {
+			ctx.logger.info(`${PACKAGE_NAME}: could not blank ${sectionName} — ${error instanceof Error ? error.message : String(error)}`);
+		}
+		prompt.context({
+			name: "library:binding",
+			order: CONTEXT_ORDER,
+			text: (context) => {
+				const id = context.agent?.session?.id;
+				if (id === void 0) return "";
+				try {
+					return renderBindingContext(service, String(id));
+				} catch {
+					return "";
+				}
+			}
+		});
+	});
+}
+//#endregion
+export { Config, LIBRARY_PROMPT, LIBRARY_TOOL_NAMES, apply, inject, libraryToolDefinitions, name, renderBindingContext };