@kirkchinese/dsh-citeciter 0.8.2 → 0.9.0-alpha.2

package/lib/types/client/host-dock.d.ts

@@ -1,4 +1,4 @@
-/** Isolated, disposable layout adapter for DSH 0.1.5-rc.1 and Desktop 2.0.9 frames. */
+/** Isolated, disposable layout adapter for DSH alpha and legacy three-column frames. */
 import { type RefObject } from 'react';
 import { type DockGeometry } from './dock-geometry.ts';
 /**
@@ -13,6 +13,8 @@ export declare function findContainingFrame(panel: HTMLElement | null): HTMLElem
  * @param panel - mounted panel reference.
  * @param open - whether space should be reserved.
  * @param percent - user's preferred fraction of the content viewport.
+ * @param floating - whether the user detached the panel.
+ * @param activation - increases only on explicit Citer navigation, permitting return from details.
  * @returns measured panel placement; null when the host frame is unsupported.
  */
-export declare function useHostDock(panel: RefObject<HTMLElement | null>, open: boolean, percent: number, floating?: boolean): DockGeometry | null;
+export declare function useHostDock(panel: RefObject<HTMLElement | null>, open: boolean, percent: number, floating?: boolean, activation?: number): DockGeometry | null;

package/lib/types/client/host-icons.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentType } from 'react';
+type Icon = ComponentType<{
+    size?: number;
+    className?: string;
+}>;
+export declare const IconSettingsOutlineMedium: Icon;
+export declare const IconQuestionOutlineMedium: Icon;
+export declare const IconSparkleMedium: Icon;
+export declare const IconDownloadOutlineMedium: Icon;
+export declare const IconThinkOutlineMedium: Icon;
+export declare const IconStopFillMedium: Icon;
+export declare const IconArchiveOutlineMedium: Icon;
+export {};

package/lib/types/client/host-image-preview.d.ts

@@ -0,0 +1,8 @@
+interface PreviewProps {
+    readonly src: string;
+    readonly alt: string;
+    readonly onClose: () => void;
+}
+/** Preview an existing authorized object URL in the host UI; the caller retains URL ownership. */
+export declare function HostImagePreview({ src, alt, onClose }: PreviewProps): import("react").JSX.Element;
+export {};

package/lib/types/client/host-ui-adapter.d.ts

@@ -0,0 +1,24 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { SettingsDescribeFace } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { SessionPendingInteraction } from '@deepseek-ai/dsh-client-ui-session/client';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+/** Stable preference operations shared by SettingsScope (0.1.5) and ConfigForm (0.1.7). */
+export interface SettingsForm<T> extends ObservableSnapshot<{
+    value: T | undefined;
+    status: 'loading' | 'ready' | 'unavailable';
+    mode: 'host' | 'memory';
+}> {
+    set(field: string, value: unknown): Promise<void>;
+    unset(field: string): Promise<void>;
+}
+interface ModernForms {
+    get<T>(namespace: string): SettingsForm<T>;
+    describe(): SettingsDescribeFace;
+}
+/** Call only public preference services. The selected service owns binding teardown. */
+export declare function hostSettings(ctx: Context): ModernForms;
+export type InteractionSnapshot = ReadonlyMap<SessionId, SessionPendingInteraction>;
+/** Normalize the renamed UI status source without creating another approval authority. */
+export declare function hostInteractions(ctx: Context): ObservableSnapshot<InteractionSnapshot>;
+export {};

package/lib/types/client/native-composer.d.ts

@@ -1,18 +1,22 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { ComposerAttachment, DraftAttachmentId, DraftFileUploads } from '@deepseek-ai/dsh-client-ui-conversation/client';
 import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
-import type { SessionFace, SessionSnapshot } from '@deepseek-ai/dsh-api-session-controller/client';
+import type { SessionFace } from '@deepseek-ai/dsh-api-session-controller/client';
+import { type CiterSessionSnapshot } from './citer-session-face.ts';
 export type DeliveryMode = 'queue' | 'steer';
+/** A lost transport response is not proof that the host rejected a submission. */
+export declare class UncertainSubmissionError extends Error {
+}
 export interface NativeComposer {
     readonly uploads: ObservableSnapshot<DraftFileUploads>;
     retry(sessionId: string, id: DraftAttachmentId): void;
-    watch(sessionId: string, listener: (snapshot: SessionSnapshot) => void): () => void;
+    watch(sessionId: string, listener: (snapshot: CiterSessionSnapshot) => void): () => void;
     queue(sessionId: string, id: Parameters<SessionFace['updateQueue']>[0], action: Parameters<SessionFace['updateQueue']>[1]): Promise<void>;
     /** Read an image or file through its owning Session's attachment authorization. */
     attachment(sessionId: string, id: string): Promise<Blob>;
     add(sessionId: string, files: readonly File[]): Promise<readonly ComposerAttachment[]>;
     remove(id: DraftAttachmentId): void;
-    send(sessionId: string, text: string, attachments: readonly DraftAttachmentId[], mode: DeliveryMode): Promise<void>;
+    send(sessionId: string, text: string, attachments: readonly DraftAttachmentId[], mode: DeliveryMode, requestId?: string): Promise<void>;
 }
 /** Adapt the installed conversation service's published composer methods; never reach its private input machine. */
 export declare function createNativeComposer(ctx: Context): NativeComposer;

package/lib/types/client/native-document.d.ts

@@ -1,13 +1,7 @@
 import type { ActionSource } from './action-controller.ts';
 import type { ReaderSelection } from './reader-selection.ts';
+import type { DocumentPreviewProps } from '@deepseek-ai/dsh-client-ui-sidebar-documentpreview/client';
 /** Decode a complete Host-owned preview buffer. Reject binary, partial and oversized imports. */
-export declare function decodeNativeText(content: {
-    readonly kind: 'text';
-    readonly text: string;
-    readonly eof: boolean;
-} | {
-    readonly kind: 'bytes';
-    readonly data: Uint8Array;
-}): string;
+export declare function decodeNativeText(content: DocumentPreviewProps['content']): string;
 /** Capture the file address's own Session and immutable text, never the later active tab. */
 export declare function nativeDocumentSource(address: string, content: string, selection: ReaderSelection): ActionSource;

package/lib/types/client/prompt.d.ts

@@ -10,6 +10,8 @@ export interface ParsedNextQuestions {
  * prose. System Tutor and Citation Context travel through their own layers.
  */
 export declare function normalizeQuestion(rawQuestion: string): string;
+/** Creation may prepare an empty composer; length limits apply before any request. */
+export declare function normalizeDraftQuestion(rawQuestion: string): string;
 /**
  * Parse optional follow-up control text without exposing complete or partial markers.
  * @param text - accumulated assistant text.

package/lib/types/client/selection-references.d.ts

@@ -0,0 +1,4 @@
+import { type ActionSource } from './action-controller.ts';
+import type { DraftReference } from './draft-references.ts';
+/** Capture an actual selected passage and its address; never reconstruct a citation from Topic metadata. */
+export declare function selectionReferences(source: ActionSource, documentId?: string): readonly DraftReference[];

package/lib/types/client/transcript-position.d.ts

@@ -1,6 +1,7 @@
 import { type UIEvent } from 'react';
-/** Keep each Topic's reading position across portal moves, view changes and close/reopen. Follow new output only while the reader is near the end. */
+/** Keep each Topic's reading position across portal moves, image loading, view changes and close/reopen. Follow new output only while the reader is near the end. */
 export declare function useTranscriptPosition(topicId: string, revision: unknown): {
     ref: (node: HTMLDivElement | null) => void;
     onScroll: (event: UIEvent<HTMLDivElement>) => void;
+    followLatest: () => void;
 };

package/lib/types/client/types.d.ts

@@ -38,6 +38,8 @@ export interface BoardCitationRequest {
 }
 export interface CiteOverlaySnapshot {
     readonly panelOpen: boolean;
+    /** Explicit navigation request, including reopening a temporarily covered panel. */
+    readonly activation: number;
     readonly presentation: PanelPresentation;
     readonly boardCitation: BoardCitationRequest | null;
 }

package/lib/types/client/update-controller.d.ts

@@ -1,4 +1,4 @@
-import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { SettingsForm as ConfigForm } from './host-ui-adapter.ts';
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
 import type { CiteCiterSettings } from '../topic.ts';
 type UpdateStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
@@ -53,7 +53,7 @@ export declare function createUpdateBrowserEnvironment(): UpdateBrowserEnvironme
  * @param reportCheckError - diagnostic sink for silent automatic-check failures.
  * @returns the root-scoped update controller.
  */
-export declare function createUpdateController(settings: SettingsScope<CiteCiterSettings>, checkUpdate: CheckUpdate, store: SnapshotStore<UpdateNoticeSnapshot>, environment?: UpdateBrowserEnvironment, reportCheckError?: (error: unknown) => void): UpdateController;
+export declare function createUpdateController(settings: ConfigForm<CiteCiterSettings>, checkUpdate: CheckUpdate, store: SnapshotStore<UpdateNoticeSnapshot>, environment?: UpdateBrowserEnvironment, reportCheckError?: (error: unknown) => void): UpdateController;
 /** @param version - validated latest package version. @param profile - active Desktop profile, or Web default. @returns the command shown and copied by the notice. */
 export declare function citeCiterUpdateCommand(version: string, profile?: string): string;
 export {};

package/lib/types/document-access.d.ts

@@ -0,0 +1,3 @@
+import type { Session } from '@deepseek-ai/dsh-session';
+/** Resolve one document from durable user submissions. Draft metadata grants no native Topic access. */
+export declare function resolveReadableDocument(session: Session | undefined, hosted: boolean, initial: string | null, requested?: string): string;

package/lib/types/document-tools.d.ts

@@ -0,0 +1,10 @@
+import type { Session } from '@deepseek-ai/dsh-session';
+/** Read an immutable document only after checking the requesting Session's submitted attachments. The caller owns authorization and storage; tools own ranges, output budgets and model-visible guidance. */
+export type AuthorizedDocumentReader = (requested: string | undefined, session: Session | undefined) => Promise<{
+    readonly documentId: string;
+    readonly content: string;
+}>;
+/** Build a bounded document reader. Offsets and documentLength count UTF-16 code units, while bytesUsed measures the UTF-8 response text. Invalid ranges remain errors; they are never silently clamped. */
+export declare function createDocumentReadTool(read: AuthorizedDocumentReader): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** Build document search independently of Topic lifecycle. Returns the document horizon so the model can expand a match without inventing an out-of-range endpoint. */
+export declare function createDocumentSearchTool(read: AuthorizedDocumentReader): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/draft-contract.d.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+/** Persisted drafts are user work, never model input until explicitly submitted. */
+export declare const draftReferenceSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        source: "source";
+        excerpt: "excerpt";
+        board: "board";
+    }>;
+    label: z.ZodString;
+    content: z.ZodString;
+    address: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const draftFileSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    name: z.ZodString;
+    type: z.ZodString;
+    size: z.ZodNumber;
+    lastModified: z.ZodNumber;
+}, z.core.$strict>;
+export declare const draftContentSchema: z.ZodObject<{
+    text: z.ZodString;
+    references: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            source: "source";
+            excerpt: "excerpt";
+            board: "board";
+        }>;
+        label: z.ZodString;
+        content: z.ZodString;
+        address: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    files: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        name: z.ZodString;
+        type: z.ZodString;
+        size: z.ZodNumber;
+        lastModified: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const draftStateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    revision: z.ZodNumber;
+    content: z.ZodObject<{
+        text: z.ZodString;
+        references: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                source: "source";
+                excerpt: "excerpt";
+                board: "board";
+            }>;
+            label: z.ZodString;
+            content: z.ZodString;
+            address: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        files: z.ZodArray<z.ZodObject<{
+            id: z.ZodUUID;
+            name: z.ZodString;
+            type: z.ZodString;
+            size: z.ZodNumber;
+            lastModified: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    pending: z.ZodNullable<z.ZodObject<{
+        requestId: z.ZodUUID;
+        content: z.ZodObject<{
+            text: z.ZodString;
+            references: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                kind: z.ZodEnum<{
+                    source: "source";
+                    excerpt: "excerpt";
+                    board: "board";
+                }>;
+                label: z.ZodString;
+                content: z.ZodString;
+                address: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            files: z.ZodArray<z.ZodObject<{
+                id: z.ZodUUID;
+                name: z.ZodString;
+                type: z.ZodString;
+                size: z.ZodNumber;
+                lastModified: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type DraftContent = z.infer<typeof draftContentSchema>;
+export type DraftState = z.infer<typeof draftStateSchema>;
+export type DraftFile = z.infer<typeof draftFileSchema>;
+export declare const EMPTY_DRAFT: DraftContent;
+export declare const EMPTY_DRAFT_STATE: DraftState;
+export declare const DRAFT_CHUNK_BYTES: number;
+/** Remove only the acknowledged submission, preserving edits made while it was pending. */
+export declare function subtractSubmitted(current: DraftContent, submitted: DraftContent): DraftContent;

package/lib/types/draft-store.d.ts

@@ -0,0 +1,23 @@
+import { type DraftFile, type DraftState } from './draft-contract.ts';
+/** Caller serializes with Topic deletion and supplies an ownership-verified Topic directory. No model log is touched. */
+export declare class DraftStore {
+    private readonly topicDirectory;
+    constructor(topicDirectory: string);
+    private directory;
+    private file;
+    /** Read validated state. Missing drafts are empty; malformed drafts remain on disk and surface an error. */
+    read(): Promise<DraftState>;
+    /** Compare-and-swap state; conflict returns the authoritative draft without overwriting either client's input. */
+    save(expected: number, next: Omit<DraftState, 'revision'>): Promise<{
+        state: DraftState;
+        conflict: boolean;
+    }>;
+    /** Reconcile an exact native admission receipt after a lost response or restart. */
+    acknowledge(state: DraftState): Promise<DraftState>;
+    /** Sequential bounded upload. Repeated identical chunks are safe after a lost response. */
+    put(meta: DraftFile, offset: number, data: string): Promise<void>;
+    /** Read only an attachment referenced by this exact saved draft, never an arbitrary path. */
+    chunk(id: string, offset: number): Promise<string>;
+    /** Delete only the verified draft subtree after the Topic is retired. */
+    remove(): Promise<void>;
+}

package/lib/types/host-agent-modules.d.ts

@@ -1,6 +1,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type AgentLoop from '@deepseek-ai/dsh-agent-loop';
 import type SessionStore from '@deepseek-ai/dsh-session';
+import type SessionTitleService from '@deepseek-ai/dsh-session-title';
 interface HostScope {
     readonly ctx: Context;
     dispose(): Promise<void>;
@@ -8,13 +9,14 @@ interface HostScope {
 export interface HostAgentModules {
     readonly AgentLoop: typeof AgentLoop;
     readonly SessionStore: typeof SessionStore;
+    readonly SessionTitleService: typeof SessionTitleService;
     readonly createScope: (ctx: Context, key: object) => HostScope;
 }
 /**
  * Resolve runtime modules from the host installation, not the plugin's dependencies.
  * CLI argv can name an npm/pnpm symlink; canonicalize it before walking node_modules.
- * Desktop retains its app.asar anchor and module identities without filesystem realpath.
- * @returns the host's AgentLoop, SessionStore and scope factory.
+ * Desktop accepts app.asar and unpacked app layouts without canonicalizing virtual paths.
+ * @returns the host's AgentLoop, SessionStore, title service and scope factory.
  * @throws when the launcher cannot be located or its runtime exports are unavailable.
  */
 export declare function loadHostAgentModules(): Promise<HostAgentModules>;

package/lib/types/host-settings-adapter.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type z from '@deepseek-ai/schemastery';
+import { type CiteCiterSettings } from './topic.ts';
+/** The 0.1.7 Cordis configuration reader. Old hosts pass no reader. */
+export interface SettingsReader {
+    get(): unknown;
+}
+/** Choose the schema mode without importing a Cordis export absent in Desktop's SDK. */
+export declare function settingsConfig(schema: z<object>): z<object>;
+/** Bind settings through the public contract of the installed host; registrations belong to ctx. */
+export declare function bindHostSettings(ctx: Context, schema: z<object>, config?: SettingsReader): () => CiteCiterSettings;

package/lib/types/index.d.ts

@@ -1,5 +1,6 @@
 /** Host entry for native Topics, legacy compatibility and the browser Remote API. */
 import { Service, type Context } from '@deepseek-ai/cordis';
+import { type SettingsReader } from './host-settings-adapter.ts';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import z from '@deepseek-ai/schemastery';
 import { type UpdateCheckResponse } from './update.ts';
@@ -15,11 +16,12 @@ export declare const CITECITER_SETTINGS_SCHEMA: z<object>;
 /** Root-scoped Remote service owning Topic metadata, native contributions and a legacy runtime. */
 export declare class CiteCiterHost extends TypertRemoteService {
     static inject: readonly ["llm", "sessionQuery", "subprocess", "agents", "agentPresets", "sessionController", "systemPrompt", "tools", "sandboxPolicy", "sessions", "sessionPersistence", "sessionTitle", "attachments"];
+    static Config: z<object>;
     private readonly topics;
     private readonly updates;
     private readonly service;
     private releaseService;
-    constructor(ctx: Context);
+    constructor(ctx: Context, config?: SettingsReader);
     /** Do not publish the Remote service until its private runtime is ready. */
     [Service.init](): Promise<void>;
     /** Resolve one create/ask command into a committed Topic snapshot. */

package/lib/types/learning-example.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+export declare const learningExampleSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    content: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"code">;
+    content: z.ZodString;
+    language: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type LearningExample = z.infer<typeof learningExampleSchema>;
+/** Native DSH tool schema; kept beside the validator to expose the same tagged contract. */
+export declare const LEARNING_EXAMPLE_PARAMETER: {
+    readonly required: true;
+    readonly description: "Choose text for prose or code for literal source code.";
+    readonly oneOf: readonly [{
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly kind: {
+                readonly type: "string";
+                readonly enum: readonly ["text"];
+                readonly required: true;
+            };
+            readonly content: {
+                readonly type: "string";
+                readonly required: true;
+                readonly description: "A prose example in Markdown, at most 1500 characters. Use the code variant for source code.";
+            };
+        };
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly kind: {
+                readonly type: "string";
+                readonly enum: readonly ["code"];
+                readonly required: true;
+            };
+            readonly content: {
+                readonly type: "string";
+                readonly required: true;
+                readonly description: "Raw source code, at most 1500 characters. Preserve line breaks and indentation; do not add Markdown fences.";
+            };
+            readonly language: {
+                readonly type: "string";
+                readonly required: true;
+                readonly description: "Language identifier such as javascript, python, html or text; 1–40 letters, digits, underscores, plus signs, dots, hashes or hyphens.";
+            };
+        };
+    }];
+};
+/** Export code literally, including embedded fences; the renderer never guesses its type. */
+export declare function learningExampleMarkdown(example: LearningExample): string;

package/lib/types/learning.d.ts

@@ -37,10 +37,24 @@ export type LearningStageId = typeof LEARNING_STAGES[number]['id'];
 export declare function learningQuestion(stageId: LearningStageId, question?: string): string;
 /** Recover the most recently requested stage from this Topic's own visible history. */
 export declare function latestLearningStage(messages: readonly TopicMessage[]): LearningStageId | null;
+/** The validation schema and model-visible native tool must expose the same field contract. */
+export declare const LEARNING_CARD_FIELD_DESCRIPTIONS: {
+    readonly title: "Non-empty title, at most 100 characters.";
+    readonly summary: "Markdown summary, at most 2000 characters. Separate independent points with lists or paragraphs; include conditions and corrections.";
+    readonly question: "Non-empty self-test question, at most 500 characters.";
+    readonly answer: "Markdown reference answer, at most 2000 characters, consistent with the summary and example. Fence multiline code.";
+};
 export declare const learningCardSchema: z.ZodObject<{
     title: z.ZodString;
     summary: z.ZodString;
-    example: z.ZodString;
+    example: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        content: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"code">;
+        content: z.ZodString;
+        language: z.ZodString;
+    }, z.core.$strict>], "kind">;
     question: z.ZodString;
     answer: z.ZodString;
 }, z.core.$strict>;
@@ -48,7 +62,14 @@ export declare const learningCardsInputSchema: z.ZodObject<{
     cards: z.ZodArray<z.ZodObject<{
         title: z.ZodString;
         summary: z.ZodString;
-        example: z.ZodString;
+        example: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"text">;
+            content: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"code">;
+            content: z.ZodString;
+            language: z.ZodString;
+        }, z.core.$strict>], "kind">;
         question: z.ZodString;
         answer: z.ZodString;
     }, z.core.$strict>>;
@@ -69,4 +90,4 @@ export declare function projectLearningCards(messages: readonly TopicMessage[]):
 /** Export the visible set with its Topic provenance; content is plain Markdown, never executed. */
 export declare function learningCardsMarkdown(cards: readonly LearningCard[], topicTitle: string, topicId: string, source: string): string;
 /** Shared teaching contract appended to every scenario's logged tutor section. */
-export declare const LEARNING_PROMPT = "The optional learning route is \u5E95\u5C42\u903B\u8F91 \u2192 \u5B9A\u6027\u5206\u6790 \u2192 \u5B9A\u91CF\u5206\u6790\uFF08\u677F\u4E66\uFF09 \u2192 \u6982\u5FF5\u5173\u8054 \u2192 \u603B\u7ED3\u5B66\u4E60\u5361\u7247. A user may select or skip any stage. Respond to the current request only; never advance automatically or claim that a stage proves mastery. Never schedule spaced repetition or reminders. Do not require quizzes before continuing.\n\nUse learning_cards only when the user asks to summarize or revise learning cards. Before composing cards in this same turn, check the Topic's conclusions and existing board for incorrect definitions, missing conditions, faulty derivations or arithmetic, and contradictions. Earlier assistant output is not evidence. Read available sources when needed; distinguish source evidence from general knowledge. Correct errors before saving, and explicitly label unresolved claims as \u672A\u6838\u5B9E (unverified) or omit them. Check every card's summary, example, question and reference answer for consistency: a correction in the summary must also reach its example and answer. Briefly report corrections and unresolved points; do not present this self-check as independent verification.\n\nEach successful learning_cards call replaces the visible card set for this Topic; older sets remain in its log. Send the complete desired set in one call, not separate calls for individual cards. Write concise, source-grounded summaries and examples, plus a question and reference answer for optional self-testing. Preserve real available source locators inside summaries; do not invent offsets, sources or evidence. Cards and blackboard tools only record learning material inside this independent Topic; they never write to the workspace or source Session.";
+export declare const LEARNING_PROMPT = "The optional learning route is \u5E95\u5C42\u903B\u8F91 \u2192 \u5B9A\u6027\u5206\u6790 \u2192 \u5B9A\u91CF\u5206\u6790\uFF08\u677F\u4E66\uFF09 \u2192 \u6982\u5FF5\u5173\u8054 \u2192 \u603B\u7ED3\u5B66\u4E60\u5361\u7247. A user may select or skip any stage. Respond to the current request only; never advance automatically or claim that a stage proves mastery. Never schedule spaced repetition or reminders. Do not require quizzes before continuing.\n\nUse learning_cards only when the user asks to summarize or revise learning cards. Before composing cards in this same turn, check the Topic's conclusions and existing board for incorrect definitions, missing conditions, faulty derivations or arithmetic, and contradictions. Earlier assistant output is not evidence. Read available sources when needed; distinguish source evidence from general knowledge. Correct errors before saving, and explicitly label unresolved claims as \u672A\u6838\u5B9E (unverified) or omit them. Check every card's summary, example, question and reference answer for consistency: a correction in the summary must also reach its example and answer. Briefly report corrections and unresolved points; do not present this self-check as independent verification.\n\nEach successful learning_cards call replaces the visible card set for this Topic; older sets remain in its log. Send the complete desired set in one call, not separate calls for individual cards. Respect the user's requested count: one card means one card, not one per stage. Write concise, source-grounded summaries and examples, plus a question and reference answer for optional self-testing. Choose example.kind=text for Markdown prose or example.kind=code for raw source code; code includes its language and preserves indentation without Markdown fences. Put explanations in the summary or answer, not around a code example. Preserve real available source locators inside summaries; do not invent offsets, sources or evidence. Cards and blackboard tools only record learning material inside this independent Topic; they never write to the workspace or source Session.";

package/lib/types/message-projection.d.ts

@@ -0,0 +1,15 @@
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+interface ContextMessage {
+    id: string;
+    content: readonly ContentBlock[];
+    source: {
+        kind: string;
+        plugin?: string;
+    };
+}
+/** Project the installed SDK's validated log. 0.1.7 split plugin context into developer/message. */
+export declare function contextMessage(event: SessionEvent): (ContextMessage & {
+    label: string;
+}) | undefined;
+export {};

package/lib/types/model-admission.d.ts

@@ -0,0 +1,7 @@
+import type { TopicMetadata } from './topic.ts';
+/** Keep an unavailable inherited route visible until the user explicitly replaces it. */
+export declare const MODEL_SELECTION_REQUIRED = "\u6765\u6E90\u6A21\u578B\u5DF2\u4E0D\u53EF\u7528\u3002\u8349\u7A3F\u5DF2\u4FDD\u7559\uFF0C\u8BF7\u9009\u62E9\u53EF\u7528\u6A21\u578B\u540E\u53D1\u9001\u3002";
+/** A retired catalog entry must not discard a newly created, still empty Topic. Other failures propagate. */
+export declare function selectInitialModel(metadata: TopicMetadata, select: () => Promise<unknown>): Promise<void>;
+/** Check the durable flag before an explicit submission, without changing permissions or model defaults. */
+export declare function requireSelectedModel(metadata: Pick<TopicMetadata, 'modelSelectionRequired'>): void;

package/lib/types/native-session-contract.d.ts

@@ -101,6 +101,7 @@ export declare const nativeAttachmentSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
 }, z.core.$strict>], "type">;
 /** Read-only control projection. The Agent inbox remains the only authoritative queue. */
 export declare const nativeStateSchema: z.ZodObject<{
+    modelSelectionRequired: z.ZodOptional<z.ZodBoolean>;
     running: z.ZodBoolean;
     blank: z.ZodBoolean;
     error: z.ZodNullable<z.ZodString>;

package/lib/types/package-version.d.ts

@@ -0,0 +1,9 @@
+/** Validate an exact package version, not an npm tag, range or CLI argument. */
+export declare function isPackageVersion(version: string): boolean;
+/**
+ * Compare complete package versions using npm SemVer precedence; build metadata does not affect order.
+ * @param installed - installed package version.
+ * @param available - version selected by the registry tag; it may be a prerelease.
+ * @returns negative, zero or positive, or null when either input is not a canonical package version.
+ */
+export declare function comparePackageVersions(installed: string, available: string): -1 | 0 | 1 | null;

package/lib/types/session-format-guard.d.ts

@@ -0,0 +1,6 @@
+export declare class NewerSessionFormatError extends Error {
+}
+/** Refuse stale writable fallback when a newer host has already produced a successor log. Never migrate logs here. */
+export declare function assertSessionFormat(directory: string): Promise<void>;
+/** Inspect only the exact owned Topic identity beneath the persistence workspace level. */
+export declare function assertOwnedSessionFormat(root: string, sessionId: string): Promise<void>;

package/lib/types/source-storage.d.ts

@@ -3,10 +3,13 @@ import type { Context } from '@deepseek-ai/cordis';
 export declare class SourceStorage {
     private readonly host;
     private readonly pending;
+    private historicalDirectories;
     constructor(host: Context);
     /** @returns a canonical source/citeciter directory, optionally creating its ownership marker. */
     root(sourceSessionId: string, create?: boolean): Promise<string | undefined>;
     private resolveRoot;
+    /** Locate historical source containers only; DSH alone reads and migrates their logs. */
+    private findHistoricalDirectories;
     /** Discover owned roots without creating directories or changing Host Session data. */
     discover(): Promise<ReadonlyMap<string, string>>;
 }

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

@@ -0,0 +1,18 @@
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** One committed tool dispatch, independent of native or run_code transport. */
+export interface ToolCallRecord {
+    readonly callId: string;
+    readonly name: string;
+    readonly arguments: string;
+}
+export interface ToolResultRecord {
+    readonly callId: string;
+    readonly content: readonly ContentBlock[];
+    readonly isError: boolean;
+    readonly meta?: SessionEvent<'tool/result'>['data']['meta'];
+}
+/** Normalize native and PTC starts using the actual child call identity. No synthetic model messages. */
+export declare function toolCallRecord(event: SessionEvent): ToolCallRecord | undefined;
+/** Normalize settled results for transcript, board, source and attachment readers. */
+export declare function toolResultRecord(event: SessionEvent): ToolResultRecord | undefined;

package/lib/types/topic-archive.d.ts

@@ -0,0 +1,5 @@
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** Return the admission time of a user inbox insertion; claims and canceled items do not qualify. */
+export declare function topicSubmissionTime(event: SessionEvent): number | null;
+/** Ignore inherited source history when repairing archive state after a restart. */
+export declare function latestTopicSubmission(events: readonly SessionEvent[], inheritedEventCount: number): number | null;

package/lib/types/topic-prompts.d.ts

@@ -1,4 +1,6 @@
-/** Shared final-answer control protocol, parsed into editable question shortcuts by the client. */
-export declare const FIRST_ANSWER_FOLLOWUPS = "After completing the first user question in this Topic, append three concise, distinct questions the user may naturally ask next, in the user's language. Put them only at the end of that first final answer, not in intermediate tool steps or later replies. Each question must deepen understanding of the answer, be at most 160 characters, and avoid unsolicited source changes or workflow actions. The UI turns them into editable drafts; never answer or send them automatically. Emit a JSON array inside this exact block, without a code fence or prose after it:\n<citeciter-next-questions>\n[\"\u95EE\u9898\u4E00\uFF1F\",\"\u95EE\u9898\u4E8C\uFF1F\",\"\u95EE\u9898\u4E09\uFF1F\"]\n</citeciter-next-questions>";
+/** Optional first-answer shortcuts. The current user's scope and output constraints take precedence over this default. */
+export declare const FIRST_ANSWER_FOLLOWUPS = "Suggested follow-up questions are an optional default, not a requirement that overrides the current request. Omit the entire suggestions block when the user asks for no suggestions or follow-up questions, only an answer/result, an exact format, or a length limit that leaves no room for suggestions. Do not explain the omission. Length and format limits apply to the complete visible response, including introductions, tables, notes and suggestions.\n\nOtherwise, after completing the first user question in this Topic, append three concise, distinct questions the user may naturally ask next, in the user's language. Put them only at the end of that first final answer, not in intermediate tool steps or later replies. Each question must deepen understanding of the answer, be at most 160 characters, and avoid unsolicited source changes or workflow actions. The UI turns them into editable drafts; never answer or send them automatically. Emit a JSON array inside this exact block, without a code fence or prose after it:\n<citeciter-next-questions>\n[\"\u95EE\u9898\u4E00\uFF1F\",\"\u95EE\u9898\u4E8C\uFF1F\",\"\u95EE\u9898\u4E09\uFF1F\"]\n</citeciter-next-questions>";
+/** Live preference overrides stale route instructions in Topic history without suppressing ordinary coding plans. */
+export declare function learningRoutePrompt(enabled: boolean): string;
 /** Compose native Topic instructions without importing legacy read-only policy or hidden citation content. */
-export declare function composeHostedTopicPrompt(custom: string | undefined, followups: boolean): string;
+export declare function composeHostedTopicPrompt(custom: string | undefined, followups: boolean, learningRoute?: boolean): string;

package/lib/types/topic-runtime.d.ts

@@ -361,8 +361,8 @@ export declare class TopicRuntime {
     private globTool;
     private learningCardsTool;
     private blackboardApplyTool;
-    private readDocumentTool;
-    private searchDocumentTool;
+    /** Keep storage and submitted-reference authorization outside the shared document tool contract. */
+    private registerDocumentTools;
     /** Share source-read instructions and contract across native and legacy Topic runtimes. */
     private registerSourceTool;
     private ensureHandle;
@@ -379,6 +379,8 @@ export declare class TopicRuntime {
     private stop;
     private rename;
     private archive;
+    /** Restore only admissions newer than the latest explicit archive; serialize with rename/delete/archive. */
+    private restoreSubmittedTopic;
     private delete;
     private deleteAdmitted;
     /** Observe the retired Session after its Agent has released write ownership. */