@khorsheed/dsh-library 0.0.0-stage → 0.1.1

package/lib/types/tool-definition.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The model-tool face of the library: one small tool per noun, each with a
+ * schema sized to its own job (schema-level required fields per operation —
+ * the mega-tool's per-`what` missing-field teaching class moved to the schema
+ * line). `library_read` answers everything read-only; the `library_<noun>`
+ * writes validate and persist what the coach authored (the card dedupe and
+ * the two-axis quiz checks live behind them); `library_assess` is the one
+ * cascading write. Content is always generated on the model side; the tools
+ * are mechanical. There is no skill to load: each tool's parameter
+ * descriptions carry its payload shape, and every refusal teaches the correct
+ * call back.
+ *
+ * A path belongs to one TEXTBOOK (a resource with a contents; proposal
+ * 2026-10-19-library-book-paths): `library_roadmap` takes the textbook as a
+ * required `resource`, and a station names that textbook's rows as
+ * `chapters: "3-4"` plus side references in `also` — both expand to the
+ * stored covers (`{ ref, locator? }`). The older spellings still parse
+ * (`covers`, `chapterRanges`, `book`, node `kind`), they are just no longer
+ * advertised. A node's `gate` says how it completes (quiz | acceptance |
+ * read).
+ *
+ * `project` / `resource` default to the session's binding (the header chip),
+ * so a bound session rarely names them; a resource id alone resolves its
+ * owner project.
+ *
+ * Every tool is a thin adapter over {@link LibraryService}, one per file in
+ * `tools/` (shared transport helpers, schemas and the per-call kit in
+ * `tools/kit.ts`). This module ASSEMBLES the definitions in workflow order
+ * and registers nothing; the package's `./tool` row (`src/tool.ts`) tags
+ * and registers them.
+ *
+ * @module @khorsheed/dsh-library/tool-definition
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { LibraryService } from './service.ts';
+import { ImageRefCache } from './image-refs.ts';
+export { chaptersLocator, splitTocText } from './tools/kit.ts';
+/** The names this module registers, in registration (workflow) order. */
+export declare const LIBRARY_TOOL_NAMES: readonly string[];
+/**
+ * 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.
+ */
+export declare function libraryToolDefinitions(service: LibraryService, images?: ImageRefCache): ToolDefinition[];
+//# sourceMappingURL=tool-definition.d.ts.map

package/lib/types/tool-definition.js

@@ -0,0 +1,49 @@
+import { ImageRefCache } from "./image-refs.js";
+import { createToolKit } from "./tools/kit.js";
+import { libraryReadTool } from "./tools/read.js";
+import { libraryProjectTool } from "./tools/project.js";
+import { libraryResourceTool } from "./tools/resource.js";
+import { libraryRoadmapTool } from "./tools/roadmap.js";
+import { libraryNotesTool } from "./tools/notes.js";
+import { libraryPageTool } from "./tools/page.js";
+import { libraryCardsTool } from "./tools/cards.js";
+import { libraryQuizTool } from "./tools/quiz.js";
+import { libraryBindingTool } from "./tools/binding.js";
+import { libraryAssessTool } from "./tools/assess.js";
+export { chaptersLocator, splitTocText } from "./tools/kit.js";
+/** The names this module registers, in registration (workflow) order. */
+export 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.
+ */
+export 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),
+    ];
+}

package/lib/types/tool.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The session-granted library tools AND the coach's prompt — this package's
+ * `./tool` composition entry for agent-preset compositions. The row provides
+ * NO service (the preset-mount isolate-realm rule forbids service rows); it
+ * registers the model tools (library_read, one library_<noun> per write,
+ * library_assess), their guidance section, and a per-turn context line naming
+ * the session's bound book and its weakest cards, all delegating to the
+ * global `ctx.library` service core the core row provides at the profile root
+ * — the official tool-row shape (the evaluation-family fold, T88). Granting
+ * is therefore per-session: a preset names the row, its sessions get all of
+ * it; every other preset's sessions get none.
+ *
+ * The row can also quiet its scope for a focused preset (the learning
+ * mode): `hideSections` blanks root prompt sections that do not apply there
+ * (a scoped section shadows a global one of the same name), and `denyTools`
+ * masks root-registered tools for the scope. Both are best-effort — a name
+ * the composition does not hold is skipped, never a boot failure.
+ *
+ * @module @khorsheed/dsh-library/tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { LibraryService } from './service.ts';
+/** Plugin configuration. */
+export interface LibraryToolConfig {
+    /**
+     * Whether this row grants the library tools: `all` (the default) or `none`
+     * (no tools, no guidance, no context — a deployment where the model must not
+     * even read the library). The core row's faces stay mounted either way.
+     */
+    tools?: 'all' | 'none';
+    /** Root prompt sections to blank in this scope (e.g. `harness:source`). */
+    hideSections?: string[];
+    /** Root-registered tools to mask in this scope (e.g. `list_capabilities`). */
+    denyTools?: string[];
+}
+export declare const Config: z;
+/** Cordis plugin name used by loader diagnostics. */
+export declare 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.
+ */
+export declare const inject: string[];
+/**
+ * The coach's guidance, registered beside the tools it describes (order 114,
+ * the eval line). Per-`what` payloads are in the tool descriptions.
+ */
+export declare const LIBRARY_PROMPT = "The library holds the learner's projects, textbooks, paths and quizzes \u2014 record them there, never only in the chat. A refusal says what to fix: fix it and resend. Quote with \u300C\u300D inside any text you pass.\n\nThe learner leads; follow this order and stop where it says:\n1. A goal \u2192 ask one or two questions (level, direction), then library_project.\n2. Textbooks \u2192 library_textbook: the learner's book (verify edition and contents online), one you pick, or one you author.\n3. A path \u2192 library_roadmap. Then describe it in two lines and STOP: the learner reviews and adopts it in the sidebar. Before that: no \u8BB2\u4E49, no teaching, no quiz.\n4. A station starts only when the learner says so (\u300C\u5F00\u59CB\u5B66\u8FD9\u4E00\u7AD9\u300D or naming it). Then write its \u8BB2\u4E49 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 \u8BB2\u4E49 missed or got something wrong, fix that section.\n5. Stuck on the material \u2192 library_cards on that point. A quiz when asked \u2192 library_quiz, then one line. Grade \u2192 library_assess.\n6. A station passed \u2192 name the next one and ask whether to start it.\n\nThe per-turn \"Library:\" context is the current state; trust it over the chat.";
+/**
+ * Render the per-turn context for one session: its binding and the weakest
+ * cards there. Kept short — it rides every turn.
+ */
+export declare function renderBindingContext(service: LibraryService, sessionId: string): string;
+/**
+ * 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.
+ */
+export declare function apply(ctx: Context, config?: LibraryToolConfig): void;
+export { libraryToolDefinitions, LIBRARY_TOOL_NAMES } from './tool-definition.ts';
+//# sourceMappingURL=tool.d.ts.map

package/lib/types/tool.js

@@ -0,0 +1,174 @@
+import z from '@deepseek-ai/schemastery';
+import { libraryToolDefinitions } from "./tool-definition.js";
+import { ImageRefCache } from "./image-refs.js";
+import { masteryReason } from "./mastery.js";
+import { profileOf } from "./profiles.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 },
+});
+export 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. */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export function renderBindingContext(service, sessionId) {
+    const summary = service.bindingSummary(sessionId, CONTEXT_CARDS);
+    if (summary.binding === undefined)
+        return 'Library: this session is not bound to a project yet.';
+    if (summary.project === undefined)
+        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 === undefined ? '.' : `, textbook 《${resource.title}》 (${resource.id}).`),
+    ];
+    if (summary.binding.previousProjectId !== undefined && summary.binding.previousProjectId !== project.id) {
+        const previous = service.projectName(summary.binding.previousProjectId);
+        lines.push(`This session worked on another project${previous === undefined ? '' : ` 「${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 === undefined
+                ? (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 === undefined ? '' : `, 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 !== undefined) {
+        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.
+ */
+export function apply(ctx, config = {}) {
+    const service = ctx.get('library');
+    if (service === undefined) {
+        ctx.logger.info(`${PACKAGE_NAME}: the global library service is absent — the library tools are not registered`);
+        return;
+    }
+    // `none` grants nothing at all (guidance about an absent tool is a wrong
+    // instruction, not a harmless one).
+    if ((config.tools ?? 'all') === 'none')
+        return;
+    // Deferred injection, NOT an apply-time probe: `ctx.get('tools')` races the
+    // tools registry's own mount order on the real composition tree.
+    // Photos: remember each session's image references as they are committed,
+    // so a recorded page carries the whole reference the model cannot see.
+    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 === undefined)
+            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)}`);
+            }
+        }
+        // The callback is synchronous; the store's reads are too, and small.
+        prompt.context({
+            name: 'library:binding',
+            order: CONTEXT_ORDER,
+            text: (context) => {
+                const id = context.agent?.session?.id;
+                if (id === undefined)
+                    return '';
+                try {
+                    return renderBindingContext(service, String(id));
+                }
+                catch {
+                    return '';
+                }
+            },
+        });
+    });
+}
+export { libraryToolDefinitions, LIBRARY_TOOL_NAMES } from "./tool-definition.js";

package/lib/types/tools/assess.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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
+ */
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import { type ToolKit } from './kit.ts';
+/** Build the `library_assess` tool over the shared kit. */
+export declare function libraryAssessTool(kit: ToolKit): ToolDefinition;
+//# sourceMappingURL=assess.d.ts.map

package/lib/types/tools/assess.js

@@ -0,0 +1,82 @@
+/**
+ * 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
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { jsonOutput, pickString, unwrap } from "./kit.js";
+/** A passed station's result carries the next step: name what follows and ask (the learner starts it). */
+function withNext(result) {
+    if (result.completed === undefined)
+        return result;
+    return { ...result, next: `Congratulate the learner, name the next station${result.unlocked !== undefined && 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. */
+export 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? }]');
+            }
+            // why is the one line the coach writes; criterion / evidence / by keep
+            // their ledger slots (older calls still send them).
+            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 !== undefined) {
+                const resource = pickString(args.resource, args.book);
+                return withNext(unwrap(await service.putAttempt({
+                    projectId: projectOf(args.project, exec, resource),
+                    nodeId: node,
+                    ...(resource === undefined ? {} : { resourceId: resource }),
+                    verdicts,
+                })));
+            }
+            const quiz = pickString(args.quiz);
+            if (quiz === undefined)
+                throw new Error('quiz is the id library_quiz returned — or pass node (an acceptance station\'s id) for acceptance');
+            const result = unwrap(await service.putAttempt({
+                projectId: projectOf(args.project, exec),
+                assessmentId: quiz,
+                verdicts,
+            }));
+            return withNext(result);
+        },
+    });
+}

package/lib/types/tools/binding.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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
+ */
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import { type ToolKit } from './kit.ts';
+/** Build the `library_binding` tool over the shared kit. */
+export declare function libraryBindingTool(kit: ToolKit): ToolDefinition;
+//# sourceMappingURL=binding.d.ts.map

package/lib/types/tools/binding.js

@@ -0,0 +1,46 @@
+/**
+ * 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
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { jsonOutput, payload, pickString, sessionIdOf, unwrap, } from "./kit.js";
+/** Build the `library_binding` tool over the shared kit. */
+export 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 === undefined)
+                throw new Error('binding needs a session — this call came from none');
+            // unbind: true (or the older binding: null) unbinds; the older nested
+            // binding { project, resource } still parses.
+            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 === undefined) {
+                throw new Error('binding needs the project: { project, resource? } (library_read · projects lists them); unbind: true to unbind');
+            }
+            // An id the shelf does not hold (a guessed slug before the textbook is
+            // registered) binds the project and says so — not a failed call.
+            if (resourceId !== undefined && !(await service.getResource({ projectId, resourceId })).ok) {
+                const bound = unwrap(await service.setBinding(sessionId, { projectId }));
+                return { ...bound, 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 === undefined ? {} : { resourceId }) }));
+        },
+    });
+}

package/lib/types/tools/cards.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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
+ */
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import { type ToolKit } from './kit.ts';
+/** Build the `library_cards` tool over the shared kit. */
+export declare function libraryCardsTool(kit: ToolKit): ToolDefinition;
+//# sourceMappingURL=cards.d.ts.map

package/lib/types/tools/cards.js

@@ -0,0 +1,100 @@
+/**
+ * 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
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { profileOf } from "../profiles.js";
+import { arrival, jsonOutput, payload, payloadList, pickString, sessionIdOf, unwrap, } from "./kit.js";
+/** Build the `library_cards` tool over the shared kit. */
+export 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 === undefined) {
+                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' };
+                // A flat sentence is the context; a card from the chat weakens unless told otherwise.
+                const context = payload(card.context) ?? (pickString(card.sentence) === undefined ? undefined : { sentence: card.sentence });
+                return {
+                    ...card,
+                    kind: card.kind === 'word' || card.kind === 'concept' ? card.kind : project.markKind,
+                    ...(card.weaken === undefined && source.type === 'chat' ? { weaken: true } : {}),
+                    source: { ...source, ...(source.type === 'chat' && source.ref === undefined && sessionId !== undefined ? { ref: sessionId } : {}) },
+                    ...(context === undefined ? {} : { context: { sentence: String(context.sentence ?? ''), ...(typeof context.node === 'string' ? { nodeId: context.node } : {}) } }),
+                };
+            });
+            // A subject project's weak point with a knowledge point lands on the point.
+            const pointed = project.pointsDriven
+                ? list.filter(card => pickString(card.point) !== undefined)
+                : [];
+            const noted = [];
+            for (const card of pointed) {
+                const station = pickString(card.node, payload(card.context)?.node) ?? (sessionId === undefined ? undefined : service.bindingSummary(sessionId, 0).station?.id);
+                if (station === undefined)
+                    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 === undefined ? {} : { resourceId: resource }),
+                    nodeId: station,
+                    pointId: pickString(card.point),
+                    text: text === '' ? String(card.gloss ?? '') : text,
+                    ...(term === undefined ? {} : { term }),
+                    ...(sessionId === undefined ? {} : { 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]));
+            // In a points-driven project a weak point from the conversation lands on
+            // a knowledge point or nowhere: a free-floating chat card is how the
+            // coach's own slips and the learner's feedback leaked in as 「弱点」.
+            if (project.pointsDriven) {
+                const loose = rest.filter(card => card.source?.type === 'chat');
+                if (loose.length > 0) {
+                    const points = sessionId === undefined ? [] : (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.`);
+                }
+            }
+            const recorded = rest.length === 0 ? undefined : unwrap(await service.writeCards({
+                projectId,
+                ...(resource === undefined ? {} : { resourceId: resource }),
+                cards: rest,
+            }));
+            return { ...(recorded ?? { ok: true }), ...(noted.length === 0 ? {} : { pointNotes: noted }) };
+        },
+    });
+}