@kirkchinese/dsh-citeciter 0.5.0 → 0.8.0

package/lib/types/client/wheel-gesture.d.ts

@@ -0,0 +1,13 @@
+import { type CiteAction, type WheelTrigger } from '../actions.ts';
+import type { ActionController, ActionSource } from './action-controller.ts';
+/** Owned reading surfaces provide captures without probing other plugins' private DOM. */
+export declare function createSelectionSurfaces(): {
+    register(element: HTMLElement, read: () => ActionSource | null): () => void;
+    read(target: EventTarget | null): ActionSource | null;
+};
+export type SelectionSurfaces = ReturnType<typeof createSelectionSurfaces>;
+/** Install hold/move/release gestures; returns a disposer removing every global listener. */
+export declare function installWheelGesture(controller: ActionController, read: (event: MouseEvent) => ActionSource | null, preferences: () => {
+    wheelTrigger?: WheelTrigger | undefined;
+    wheelSlots?: (CiteAction | null)[] | undefined;
+}): () => void;

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

@@ -0,0 +1,4 @@
+/** Shared Host/Client page budget; full text stays in the document owner. */
+export declare const DOCUMENT_CONTENT_MAX_BYTES: number;
+/** Split UTF-8 text without breaking code points; concatenation exactly reproduces the input. */
+export declare function documentPages(content: string): string[];

package/lib/types/documents.d.ts

@@ -1,6 +1,5 @@
 import { type DocumentContent, type DocumentFormat, type DocumentSummary } from './topic.ts';
-/** Reader page budget keeps one document-get response comfortably bounded. */
-export declare const DOCUMENT_CONTENT_MAX_BYTES: number;
+export { DOCUMENT_CONTENT_MAX_BYTES } from './document-pages.ts';
 interface DocumentRecordFile {
     readonly schemaVersion: 1;
     readonly documentId: string;
@@ -12,8 +11,11 @@ interface DocumentRecordFile {
 /** Validate and persist one imported text document under the private library. */
 export declare class DocumentStore {
     private readonly root;
+    private readonly summaries;
     /** @param root - private document library root. */
     constructor(root?: string);
+    /** Read validated, immutable metadata without loading the document body. Missing documents return null; successful reads are cached for this store's lifetime. */
+    summary(documentId: string): Promise<DocumentSummary | null>;
     /**
      * Persist one imported document and its normalized UTF-8 text.
      * @param input - validated title, format, and content from the import boundary.
@@ -38,8 +40,8 @@ export declare class DocumentStore {
     /**
      * Return one bounded Reader page.
      * @param documentId - private document identity.
-     * @returns the first content window, truncated when the text exceeds the page budget.
+     * @param pageIndex - zero-based page; omitted requests the first page. Out-of-range pages are rejected.
+     * @returns a UTF-8-budgeted page and the total page count; Unicode code points are never split.
      */
-    get(documentId: string): Promise<DocumentContent>;
+    get(documentId: string, pageIndex?: number): Promise<DocumentContent>;
 }
-export {};

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

@@ -0,0 +1,15 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type AgentLoop from '@deepseek-ai/dsh-agent-loop';
+import type SessionStore from '@deepseek-ai/dsh-session';
+interface HostScope {
+    readonly ctx: Context;
+    dispose(): Promise<void>;
+}
+export interface HostAgentModules {
+    readonly AgentLoop: typeof AgentLoop;
+    readonly SessionStore: typeof SessionStore;
+    readonly createScope: (ctx: Context, key: object) => HostScope;
+}
+/** Resolve published runtime modules from the actual launcher, preserving Desktop's module identities across external-plugin fallback paths. */
+export declare function loadHostAgentModules(): Promise<HostAgentModules>;
+export {};

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

@@ -0,0 +1,31 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import { type SessionEvent } from '@deepseek-ai/dsh-session';
+import type { CiteCiterSettings, TopicMetadata } from './topic.ts';
+/** Host-owned session services; Citer owns only its scoped contributions and factory handles. */
+export declare class HostSessionAdapter {
+    private readonly ctx;
+    private readonly settings;
+    private readonly assemble;
+    private readonly storageRoot;
+    private readonly metadata;
+    private readonly scopes;
+    private readonly worlds;
+    private readonly access;
+    private disposal;
+    constructor(ctx: Context, settings: () => CiteCiterSettings, assemble: (scope: Context, agent: Agent, metadata: TopicMetadata) => Promise<void>, storageRoot: (metadata: TopicMetadata) => string);
+    /** Drain owned factories before removing their native checkpoint routes. */
+    private dispose;
+    /** Retain navigation metadata before the Host can resume this identity. */
+    remember(metadata: TopicMetadata): void;
+    /** Resolve the Topic's factory/persistence realm, retaining old candidate records without deleting Host files. */
+    context(metadata: TopicMetadata): Promise<Context>;
+    /** Release a complete owned Topic realm before deleting its files. */
+    retire(metadata: TopicMetadata): Promise<void>;
+    /** Compose a Topic on a native Agent without replacing its loop, tools or permission service. */
+    private attach;
+    /** Create a native Session with an explicit initial permission. Citer supplies an empty seed so removed references cannot leak through inherited history. No prompt is sent here. */
+    create(metadata: TopicMetadata, seed: readonly SessionEvent[], signal?: AbortSignal): Promise<AgentHandle>;
+    /** Resume with the Host's preset and preserve the user's logged permission. */
+    resume(metadata: TopicMetadata, signal?: AbortSignal): Promise<AgentHandle>;
+}

package/lib/types/index.d.ts

@@ -1,4 +1,4 @@
-/** Host entry for private Observer Topics and their browser Remote API. */
+/** Host entry for native Topics, legacy compatibility and the browser Remote API. */
 import { Service, type Context } from '@deepseek-ai/cordis';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import z from '@deepseek-ai/schemastery';
@@ -6,15 +6,15 @@ import { type UpdateCheckResponse } from './update.ts';
 import { type CiteCiterRequest, type CiteCiterResponse } from './topic.ts';
 /** Cordis/Typert package identity. */
 export declare const name = "@kirkchinese/dsh-citeciter";
-/** Services required by the private Topic runtime. */
-export declare const inject: readonly ["llm", "sessionQuery", "subprocess"];
+/** Explicit dependencies for native session composition and legacy compatibility. */
+export declare const inject: readonly ["llm", "sessionQuery", "subprocess", "agents", "agentPresets", "sessionController", "systemPrompt", "tools", "sandboxPolicy", "sessions", "sessionPersistence", "sessionTitle", "attachments"];
 /** Host settings identity shared with the browser settings scope. */
-export declare const CITECITER_SETTINGS_NS: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export declare const CITECITER_SETTINGS_NS: "citeciter";
 /** Native settings schema for new Topics and the companion panel. */
 export declare const CITECITER_SETTINGS_SCHEMA: z<object>;
-/** Root-scoped Remote service owning one isolated DSH runtime. */
+/** 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"];
+    static inject: readonly ["llm", "sessionQuery", "subprocess", "agents", "agentPresets", "sessionController", "systemPrompt", "tools", "sandboxPolicy", "sessions", "sessionPersistence", "sessionTitle", "attachments"];
     private readonly topics;
     private readonly updates;
     private readonly service;

package/lib/types/learning.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import type { TopicMessage } from './topic.ts';
+/** User-selected teaching stages; these indicate intent, never measured mastery. */
+export declare const LEARNING_STAGES: readonly [{
+    readonly id: "logic";
+    readonly label: "底层逻辑";
+    readonly shortLabel: "逻辑";
+    readonly hint: "从定义、成立条件和因果机制讲起。";
+    readonly instruction: "请讲清当前主题的底层逻辑：先给出定义和成立条件，再解释因果机制与为什么成立。区分来源证据、一般知识和假设。只讲这一阶段，不自动推进。";
+}, {
+    readonly id: "qualitative";
+    readonly label: "定性分析";
+    readonly shortLabel: "定性";
+    readonly hint: "看方向、边界，以及改变条件会发生什么。";
+    readonly instruction: "请对当前主题做定性分析：解释变量或因素之间的关系、变化方向、边界与反例，用一个具体情境说明。只讲这一阶段，不自动推进。";
+}, {
+    readonly id: "quantitative";
+    readonly label: "定量分析（板书）";
+    readonly shortLabel: "定量";
+    readonly hint: "把变量、推导和算例写到板书上。";
+    readonly instruction: "请对当前主题做定量分析，并调用 blackboard_apply 整理板书：注明变量、单位、假设、推导步骤与一个可核查算例。示例数值必须标明是假设，不得伪造来源数据。如果此主题不适合定量或信息不足，请明确说明原因。只讲这一阶段，不自动推进。";
+}, {
+    readonly id: "connections";
+    readonly label: "概念关联";
+    readonly shortLabel: "关联";
+    readonly hint: "说明它与哪些概念相连，以及为什么。";
+    readonly instruction: "请围绕当前主题给出 2–4 个最有帮助的概念关联，逐一解释是前提、推论、类比还是对比，说明关联理由与类比的边界。需要时用板书画关系。只讲这一阶段，不自动推进。";
+}, {
+    readonly id: "summary";
+    readonly label: "总结学习卡片";
+    readonly shortLabel: "总结";
+    readonly hint: "先核对与纠错，再整理成学习卡片。";
+    readonly instruction: "请先核对本 Topic 的结论与已有板书：检查定义、成立条件、推导、数值和前后矛盾，不要把此前的模型回答当作证据；必要时读取可用来源。纠正发现的错误，将无法核实的内容明确标为“未核实”或省略，不要补造来源与定位。然后调用 learning_cards 生成 1–6 张学习卡片，每张包含核心结论、一个具体例子、可选自测问题和参考答案；逐项检查这些字段的一致性，纠错必须同步到例子和参考答案。涉及来源事实时保留真实可用的定位，区分来源证据与一般知识。完成后简短说明纠正了什么、还有哪些内容未核实；不安排复习计划。";
+}];
+export type LearningStageId = typeof LEARNING_STAGES[number]['id'];
+/** Make the entire stage instruction visible and durable as an ordinary Topic user message. */
+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;
+export declare const learningCardSchema: z.ZodObject<{
+    title: z.ZodString;
+    summary: z.ZodString;
+    example: z.ZodString;
+    question: z.ZodString;
+    answer: z.ZodString;
+}, z.core.$strict>;
+export declare const learningCardsInputSchema: z.ZodObject<{
+    cards: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        summary: z.ZodString;
+        example: z.ZodString;
+        question: z.ZodString;
+        answer: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type LearningCard = z.infer<typeof learningCardSchema>;
+export interface LearningCardsProjection {
+    readonly cards: readonly LearningCard[];
+    /** Successful tool message owning this set, or null before any valid set exists. */
+    readonly messageId: string | null;
+    readonly invalid: number;
+}
+/**
+ * Recover the latest complete card set from successful Topic tool records.
+ * Pending, failed and malformed records cannot replace the previous valid set.
+ * No separate storage or migration is needed; older sets remain in the Topic log.
+ */
+export declare function projectLearningCards(messages: readonly TopicMessage[]): LearningCardsProjection;
+/** 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.";

package/lib/types/native-attachment-read.d.ts

@@ -0,0 +1,19 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+/**
+ * Read an image or verbatim file only after finding its reference in this Topic.
+ * @param ctx - the owned Agent context supplying the native attachment store.
+ * @param session - the exact Citer log authorizing the requested identity.
+ * @param id - opaque attachment identity; never interpreted as a filesystem path.
+ * @param signal - cancellation propagated to the host reader.
+ * @returns the durable image/file reference and base64 bytes for the remote client.
+ * Native readers retain byte-integrity checks. The browser materializes the complete
+ * attachment for preview/download; this operation never reads the source Session.
+ */
+export declare function readNativeAttachment(ctx: Context, session: Session, id: string, signal: AbortSignal): Promise<{
+    attachment: import("@deepseek-ai/dsh-attachment").ImageAttachmentRef;
+    data: string;
+} | {
+    attachment: import("@deepseek-ai/dsh-attachment").FileAttachmentRef;
+    data: string;
+}>;

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

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+export declare const nativeImageSchema: z.ZodPipe<z.ZodObject<{
+    attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+    mediaType: z.ZodEnum<{
+        "image/png": "image/png";
+        "image/jpeg": "image/jpeg";
+        "image/webp": "image/webp";
+        "image/gif": "image/gif";
+    }>;
+    bytes: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    name: z.ZodOptional<z.ZodString>;
+    originalDimensions: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodTransform<ImageAttachmentRef, {
+    attachmentId: AttachmentIdType;
+    mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+    bytes: number;
+    width: number;
+    height: number;
+    name?: string | undefined;
+    originalDimensions?: {
+        width: number;
+        height: number;
+    } | undefined;
+}>>;
+/** Wire reference for an authorized attachment; generic files have no image metadata. */
+export declare const nativeAttachmentRefSchema: z.ZodUnion<readonly [z.ZodPipe<z.ZodObject<{
+    attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+    mediaType: z.ZodEnum<{
+        "image/png": "image/png";
+        "image/jpeg": "image/jpeg";
+        "image/webp": "image/webp";
+        "image/gif": "image/gif";
+    }>;
+    bytes: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    name: z.ZodOptional<z.ZodString>;
+    originalDimensions: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodTransform<ImageAttachmentRef, {
+    attachmentId: AttachmentIdType;
+    mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+    bytes: number;
+    width: number;
+    height: number;
+    name?: string | undefined;
+    originalDimensions?: {
+        width: number;
+        height: number;
+    } | undefined;
+}>>, z.ZodObject<{
+    attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+    name: z.ZodString;
+    bytes: z.ZodNumber;
+}, z.core.$strict>]>;
+export declare const nativeAttachmentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    attachment: z.ZodPipe<z.ZodObject<{
+        attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+        mediaType: z.ZodEnum<{
+            "image/png": "image/png";
+            "image/jpeg": "image/jpeg";
+            "image/webp": "image/webp";
+            "image/gif": "image/gif";
+        }>;
+        bytes: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        name: z.ZodOptional<z.ZodString>;
+        originalDimensions: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodTransform<ImageAttachmentRef, {
+        attachmentId: AttachmentIdType;
+        mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+        bytes: number;
+        width: number;
+        height: number;
+        name?: string | undefined;
+        originalDimensions?: {
+            width: number;
+            height: number;
+        } | undefined;
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    attachment: z.ZodObject<{
+        attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+        name: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">;
+/** Read-only control projection. The Agent inbox remains the only authoritative queue. */
+export declare const nativeStateSchema: z.ZodObject<{
+    running: z.ZodBoolean;
+    blank: z.ZodBoolean;
+    error: z.ZodNullable<z.ZodString>;
+    queue: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        placement: z.ZodEnum<{
+            queued: "queued";
+            steering: "steering";
+            context: "context";
+        }>;
+        rpcId: z.ZodOptional<z.ZodString>;
+        text: z.ZodString;
+        attachments: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            attachment: z.ZodPipe<z.ZodObject<{
+                attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+                mediaType: z.ZodEnum<{
+                    "image/png": "image/png";
+                    "image/jpeg": "image/jpeg";
+                    "image/webp": "image/webp";
+                    "image/gif": "image/gif";
+                }>;
+                bytes: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                name: z.ZodOptional<z.ZodString>;
+                originalDimensions: z.ZodOptional<z.ZodObject<{
+                    width: z.ZodNumber;
+                    height: z.ZodNumber;
+                }, z.core.$strict>>;
+            }, z.core.$strict>, z.ZodTransform<ImageAttachmentRef, {
+                attachmentId: AttachmentIdType;
+                mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+                bytes: number;
+                width: number;
+                height: number;
+                name?: string | undefined;
+                originalDimensions?: {
+                    width: number;
+                    height: number;
+                } | undefined;
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"file">;
+            attachment: z.ZodObject<{
+                attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+                name: z.ZodString;
+                bytes: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>], "type">>;
+    }, z.core.$strict>>;
+    receipts: z.ZodArray<z.ZodObject<{
+        requestId: z.ZodString;
+        attachments: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            attachment: z.ZodPipe<z.ZodObject<{
+                attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+                mediaType: z.ZodEnum<{
+                    "image/png": "image/png";
+                    "image/jpeg": "image/jpeg";
+                    "image/webp": "image/webp";
+                    "image/gif": "image/gif";
+                }>;
+                bytes: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                name: z.ZodOptional<z.ZodString>;
+                originalDimensions: z.ZodOptional<z.ZodObject<{
+                    width: z.ZodNumber;
+                    height: z.ZodNumber;
+                }, z.core.$strict>>;
+            }, z.core.$strict>, z.ZodTransform<ImageAttachmentRef, {
+                attachmentId: AttachmentIdType;
+                mediaType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+                bytes: number;
+                width: number;
+                height: number;
+                name?: string | undefined;
+                originalDimensions?: {
+                    width: number;
+                    height: number;
+                } | undefined;
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"file">;
+            attachment: z.ZodObject<{
+                attachmentId: z.ZodPipe<z.ZodString, z.ZodTransform<AttachmentIdType, string>>;
+                name: z.ZodString;
+                bytes: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>], "type">>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type NativeState = z.infer<typeof nativeStateSchema>;
+export type NativeAttachment = z.infer<typeof nativeAttachmentSchema>;

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

@@ -0,0 +1,4 @@
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { NativeState } from './native-session-contract.ts';
+/** Read native inbox occurrences and requested admission receipts without registering a Host list row. */
+export declare function readNativeState(agent: Agent, requestIds: readonly string[]): NativeState;

package/lib/types/observer.d.ts

@@ -1,5 +1,6 @@
 export { projectDiffMeta, projectToolEvidence, projectToolResultText, type ToolEvidenceProjection, } from './evidence-text.ts';
-import { type JsonValue, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session';
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session';
+import { type JsonValue } from '@deepseek-ai/dsh-util-values';
 import { type CitationEvidence, type CitationSelectionClaim, type CitationDraft, type DocumentEvidenceClaim, type ToolEvidenceClaim } from './topic.ts';
 /** One atomic live-preferred SessionQuery observation. */
 export interface ObserverSourceSnapshot {

package/lib/types/owned-session-cleanup.d.ts

@@ -0,0 +1,2 @@
+/** Delete a retired Topic's private backend, including its child Agents. The caller must drain the factory and verify its source ownership marker first. Never accepts the Host backend root. */
+export declare function removeOwnedSessionTree(topicDirectory: string): Promise<void>;

package/lib/types/service.d.ts

@@ -62,7 +62,7 @@ export interface CiteCiterService {
     /**
      * List Topics grouped by their source session.
      * @param sourceSessionId - source DSH Session identity.
-     * @param includeArchived - include archived Topics when true.
+     * @param includeArchived - select archived Topics when true; otherwise select active Topics.
      * @param signal - caller cancellation.
      * @returns summaries sorted by update time descending.
      */

package/lib/types/session-migration.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Copy a validated Session through public persistence handles. Resume an interrupted identical prefix; never overwrite divergent data or remove the original. Close both handles before returning. */
+export declare function copySessionHistory(source: Context['sessionPersistence'], target: Context['sessionPersistence'], sessionId: string): Promise<void>;

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

@@ -0,0 +1,7 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type Session } from '@deepseek-ai/dsh-session';
+import type { ObserverSourceSnapshot } from './observer.ts';
+/** Read one consistent source cut. Release the observation even when copying fails. */
+export declare function readSourceSession(ctx: Context, id: string): Promise<ObserverSourceSnapshot>;
+/** Only an explicitly sent attachment enables later tool reads; unsent metadata grants nothing. */
+export declare function hasSentSource(session: Session | undefined, address: string): boolean;

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

@@ -0,0 +1,12 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Locate only source-owned Citer directories through the installed JSONL backend; persisted paths are never trusted. */
+export declare class SourceStorage {
+    private readonly host;
+    private readonly pending;
+    constructor(host: Context);
+    /** @returns a canonical source/citeciter directory, optionally creating its ownership marker. */
+    root(sourceSessionId: string, create?: boolean): Promise<string | undefined>;
+    private resolveRoot;
+    /** Discover owned roots without creating directories or changing Host Session data. */
+    discover(): Promise<ReadonlyMap<string, string>>;
+}

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

@@ -0,0 +1,75 @@
+import { type SessionHeader } from '@deepseek-ai/dsh-session';
+import { z } from 'zod';
+import { type TopicMetadata } from './topic.ts';
+export declare function errorCode(error: unknown): string | undefined;
+export declare function unlinkIfPresent(path: string): Promise<void>;
+export declare function rmdirIfEmpty(path: string): Promise<void>;
+/**
+ * Remove one artifact from a caller-owned JSONL root without following links.
+ * @param root - fixed private JSONL root owned by the caller.
+ * @param artifact - location returned by that exact JSONL backend.
+ * @returns when the file/link and its empty per-session directory are absent.
+ */
+export declare function removeOwnedJsonlArtifact(root: string, artifact: {
+    readonly kind: string;
+    readonly path: string;
+} | undefined): Promise<void>;
+/**
+ * Delete all JSONL generations of an already retired private Topic.
+ * DSH 0.1.5 has no public delete/location API. This bounded disk adapter follows
+ * its project/Session directory layout and canonical generation filenames.
+ * @param root - exclusively owned CiteCiter Session root, never a host Session root.
+ * @param sessionId - generated CiteCiter identity; arbitrary path segments are refused.
+ * @returns after every canonical generation and the retired lock file are absent.
+ */
+export declare function removeOwnedTopicGenerations(root: string, sessionId: string): Promise<void>;
+declare const topicDeletionMarkerSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    storage: z.ZodOptional<z.ZodLiteral<"source">>;
+    sessionId: z.ZodString;
+    sourceSessionId: z.ZodString;
+    topicId: z.ZodNumber;
+    sessionHeader: z.ZodObject<{
+        version: z.ZodNumber;
+        id: z.ZodString;
+        createdAt: z.ZodNumber;
+        isSeeded: z.ZodDefault<z.ZodBoolean>;
+        cwd: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type TopicDeletionMarker = Omit<z.infer<typeof topicDeletionMarkerSchema>, 'sessionHeader'> & {
+    readonly sessionHeader: SessionHeader;
+};
+/** Minimal on-disk navigation index; Session history stays in standard DSH JSONL. */
+export declare class TopicIndex {
+    private readonly root;
+    private readonly sourceRoots;
+    /** Bind a canonical source-owned root resolved by SourceStorage. */
+    bindSource(sourceSessionId: string, root: string): void;
+    /** Return the owned metadata directory for one source-backed Topic. */
+    ownedDirectory(sourceSessionId: string, topicId: number): string;
+    /** @param root - private Topic index root. */
+    constructor(root?: string);
+    /** Read navigation records across sources; never opens or mutates a Session log. */
+    all(includeSuperseded?: boolean): Promise<TopicMetadata[]>;
+    reserve(sourceSessionId: string): Promise<{
+        topicId: number;
+        directory: string;
+    }>;
+    save(metadata: TopicMetadata): Promise<void>;
+    loadBySessionId(sessionId: string): Promise<TopicMetadata>;
+    list(sourceSessionId: string): Promise<TopicMetadata[]>;
+    /** Commit a minimal deletion marker before making Topic metadata unreachable. */
+    markDeleting(metadata: TopicMetadata, sessionHeader: SessionHeader): Promise<TopicDeletionMarker>;
+    /** Discover committed deletion markers without following linked directories. */
+    listDeleting(): Promise<TopicDeletionMarker[]>;
+    /** Remove the marker and its now-empty Topic directory after artifact cleanup. */
+    finishDeleting(marker: TopicDeletionMarker): Promise<void>;
+    /** Forget only a superseded plugin index after an owned copy was committed; original logs remain intact. */
+    forgetLegacy(metadata: Pick<TopicMetadata, 'sessionId' | 'sourceSessionId' | 'topicId'>): Promise<void>;
+    private directory;
+    private read;
+    private readIfPresent;
+    private deletionMarkerIfPresent;
+}
+export {};