@kirkchinese/dsh-citeciter 0.2.0 → 0.3.0

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

@@ -0,0 +1,50 @@
+import { Context } from '@deepseek-ai/cordis';
+import { type CiteCiterRequest, type CiteCiterResponse, type CiteCiterSettings } from './topic.ts';
+/** One process-local private DSH tree with standard Session logs and Agent loop. */
+export declare class TopicRuntime {
+    private readonly host;
+    private readonly settings;
+    private readonly runtime;
+    private readonly index;
+    private readonly fibers;
+    private readonly handles;
+    private readonly selections;
+    private readonly opening;
+    private readonly ready;
+    private disposal;
+    private releasing;
+    private releaseLlm;
+    private releaseFs;
+    private releaseSandboxPolicy;
+    private hasSourceFiles;
+    private closed;
+    /** @param host - owning DSH context. @param settings - current user preferences. */
+    constructor(host: Context, settings?: () => CiteCiterSettings);
+    /** Wait until every private DSH service has started. */
+    initialize(): Promise<void>;
+    /** Execute one validated browser command against private Topics. */
+    request(rawRequest: CiteCiterRequest): Promise<CiteCiterResponse>;
+    /** Stop every owned Agent and plugin fiber before releasing bridged services. */
+    dispose(): Promise<void>;
+    private disposeOwned;
+    private start;
+    private releaseRuntime;
+    private releaseOwnedRuntime;
+    private create;
+    private createHandle;
+    private setupAgent;
+    private sourceTool;
+    private ensureHandle;
+    private ask;
+    private stop;
+    private rename;
+    private archive;
+    private delete;
+    private removeSessionArtifact;
+    private selectModel;
+    private models;
+    private list;
+    private readLog;
+    private sourceAvailable;
+    private snapshot;
+}

package/lib/types/topic.d.ts

@@ -0,0 +1,419 @@
+import { z } from 'zod';
+/** Durable Citation version used by Observer Topics. */
+export declare const CITATION_SCHEMA_VERSION: 3;
+/** Navigation metadata version. Chat history remains in the DSH Session log. */
+export declare const TOPIC_METADATA_SCHEMA_VERSION: 1;
+/** Host settings namespace mirrored by the browser settings scope. */
+export declare const CITECITER_SETTINGS_NAMESPACE: "citeciter";
+/** Topic-scoped system prompt section. */
+export declare const TUTOR_SECTION_NAME: "@kirkchinese/dsh-citeciter:tutor";
+/** Topic-scoped, user-role Citation context. */
+export declare const CITATION_CONTEXT_NAME: "@kirkchinese/dsh-citeciter:citation";
+export declare const topicModeSchema: z.ZodEnum<{
+    observer: "observer";
+    "exact-fork": "exact-fork";
+}>;
+export type TopicMode = z.infer<typeof topicModeSchema>;
+/** User preferences applied to new Topics and source reads. */
+export declare const citeCiterSettingsSchema: z.ZodObject<{
+    defaultMode: z.ZodEnum<{
+        observer: "observer";
+        "exact-when-available": "exact-when-available";
+    }>;
+    includeSourceReasoning: z.ZodBoolean;
+    allowSourceFiles: z.ZodBoolean;
+    panelWidthPercent: z.ZodNumber;
+    reopenLastTopic: z.ZodBoolean;
+}, z.core.$strict>;
+export type CiteCiterSettings = z.infer<typeof citeCiterSettingsSchema>;
+/** Settings used before an optional DSH settings provider becomes available. */
+export declare const DEFAULT_CITECITER_SETTINGS: CiteCiterSettings;
+/** Host-verifiable Markdown evidence plus the browser-visible quote used by the UI. */
+export declare const citationDraftSchema: z.ZodObject<{
+    sourceSessionId: z.ZodString;
+    anchorSeq: z.ZodNumber;
+    startOffset: z.ZodNumber;
+    endOffset: z.ZodNumber;
+    sourceText: z.ZodString;
+    displayText: z.ZodString;
+    prefixText: z.ZodString;
+    suffixText: z.ZodString;
+    selectionFingerprint: z.ZodString;
+}, z.core.$strict>;
+/** Browser-captured selection submitted for authoritative Host validation. */
+export type CitationDraft = z.infer<typeof citationDraftSchema>;
+export declare const citationRecordSchema: z.ZodObject<{
+    sourceSessionId: z.ZodString;
+    anchorSeq: z.ZodNumber;
+    startOffset: z.ZodNumber;
+    endOffset: z.ZodNumber;
+    sourceText: z.ZodString;
+    displayText: z.ZodString;
+    prefixText: z.ZodString;
+    suffixText: z.ZodString;
+    selectionFingerprint: z.ZodString;
+    schemaVersion: z.ZodLiteral<3>;
+    createdAt: z.ZodNumber;
+}, z.core.$strict>;
+/** Immutable evidence identity owned by one Topic. */
+export type CitationRecord = z.infer<typeof citationRecordSchema>;
+export declare const modelConfigSchema: z.ZodObject<{
+    provider: z.ZodString;
+    model: z.ZodString;
+    reasoningEffort: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    stop: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type TopicModelConfig = z.infer<typeof modelConfigSchema>;
+export declare const topicMetadataSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    topicId: z.ZodNumber;
+    sessionId: z.ZodString;
+    sourceSessionId: z.ZodString;
+    sourceCwd: z.ZodString;
+    mode: z.ZodEnum<{
+        observer: "observer";
+        "exact-fork": "exact-fork";
+    }>;
+    citation: z.ZodObject<{
+        sourceSessionId: z.ZodString;
+        anchorSeq: z.ZodNumber;
+        startOffset: z.ZodNumber;
+        endOffset: z.ZodNumber;
+        sourceText: z.ZodString;
+        displayText: z.ZodString;
+        prefixText: z.ZodString;
+        suffixText: z.ZodString;
+        selectionFingerprint: z.ZodString;
+        schemaVersion: z.ZodLiteral<3>;
+        createdAt: z.ZodNumber;
+    }, z.core.$strict>;
+    modelConfig: z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+        reasoningEffort: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        stop: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    forkThroughSeq: z.ZodNullable<z.ZodNumber>;
+    temporaryTitle: z.ZodString;
+    cachedTitle: z.ZodNullable<z.ZodString>;
+    cachedTitleSource: z.ZodNullable<z.ZodEnum<{
+        provider: "provider";
+        fallback: "fallback";
+        user: "user";
+    }>>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+    archivedAt: z.ZodNullable<z.ZodNumber>;
+    sourceAvailable: z.ZodBoolean;
+}, z.core.$strict>;
+/** Small navigation record stored outside the standard Topic Session log. */
+export type TopicMetadata = z.infer<typeof topicMetadataSchema>;
+export declare const topicSummarySchema: z.ZodObject<{
+    topicId: z.ZodNumber;
+    sessionId: z.ZodString;
+    sourceSessionId: z.ZodString;
+    mode: z.ZodEnum<{
+        observer: "observer";
+        "exact-fork": "exact-fork";
+    }>;
+    citation: z.ZodObject<{
+        sourceSessionId: z.ZodString;
+        anchorSeq: z.ZodNumber;
+        startOffset: z.ZodNumber;
+        endOffset: z.ZodNumber;
+        sourceText: z.ZodString;
+        displayText: z.ZodString;
+        prefixText: z.ZodString;
+        suffixText: z.ZodString;
+        selectionFingerprint: z.ZodString;
+        schemaVersion: z.ZodLiteral<3>;
+        createdAt: z.ZodNumber;
+    }, z.core.$strict>;
+    title: z.ZodString;
+    titlePending: z.ZodBoolean;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+    archived: z.ZodBoolean;
+    running: z.ZodBoolean;
+    sourceAvailable: z.ZodBoolean;
+    observedThroughSeq: z.ZodNullable<z.ZodNumber>;
+    modelConfig: z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+        reasoningEffort: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        stop: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type TopicSummary = z.infer<typeof topicSummarySchema>;
+export declare const topicMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    seq: z.ZodNumber;
+    role: z.ZodEnum<{
+        error: "error";
+        user: "user";
+        assistant: "assistant";
+    }>;
+    text: z.ZodString;
+    reasoning: z.ZodNullable<z.ZodString>;
+    streaming: z.ZodBoolean;
+}, z.core.$strict>;
+export type TopicMessage = z.infer<typeof topicMessageSchema>;
+export declare const topicSnapshotSchema: z.ZodObject<{
+    topic: z.ZodObject<{
+        topicId: z.ZodNumber;
+        sessionId: z.ZodString;
+        sourceSessionId: z.ZodString;
+        mode: z.ZodEnum<{
+            observer: "observer";
+            "exact-fork": "exact-fork";
+        }>;
+        citation: z.ZodObject<{
+            sourceSessionId: z.ZodString;
+            anchorSeq: z.ZodNumber;
+            startOffset: z.ZodNumber;
+            endOffset: z.ZodNumber;
+            sourceText: z.ZodString;
+            displayText: z.ZodString;
+            prefixText: z.ZodString;
+            suffixText: z.ZodString;
+            selectionFingerprint: z.ZodString;
+            schemaVersion: z.ZodLiteral<3>;
+            createdAt: z.ZodNumber;
+        }, z.core.$strict>;
+        title: z.ZodString;
+        titlePending: z.ZodBoolean;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+        archived: z.ZodBoolean;
+        running: z.ZodBoolean;
+        sourceAvailable: z.ZodBoolean;
+        observedThroughSeq: z.ZodNullable<z.ZodNumber>;
+        modelConfig: z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodString;
+            reasoningEffort: z.ZodOptional<z.ZodString>;
+            temperature: z.ZodOptional<z.ZodNumber>;
+            maxTokens: z.ZodOptional<z.ZodNumber>;
+            stop: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    messages: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        seq: z.ZodNumber;
+        role: z.ZodEnum<{
+            error: "error";
+            user: "user";
+            assistant: "assistant";
+        }>;
+        text: z.ZodString;
+        reasoning: z.ZodNullable<z.ZodString>;
+        streaming: z.ZodBoolean;
+    }, z.core.$strict>>;
+    error: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type TopicSnapshot = z.infer<typeof topicSnapshotSchema>;
+export declare const modelOptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    reasoningEfforts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const providerOptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    models: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        reasoningEfforts: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ProviderOption = z.infer<typeof providerOptionSchema>;
+/** One strict direct-RPC command for the private CiteCiter runtime. */
+export declare const citeCiterRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"create">;
+    citation: z.ZodObject<{
+        sourceSessionId: z.ZodString;
+        anchorSeq: z.ZodNumber;
+        startOffset: z.ZodNumber;
+        endOffset: z.ZodNumber;
+        sourceText: z.ZodString;
+        displayText: z.ZodString;
+        prefixText: z.ZodString;
+        suffixText: z.ZodString;
+        selectionFingerprint: z.ZodString;
+    }, z.core.$strict>;
+    question: z.ZodString;
+    mode: z.ZodEnum<{
+        observer: "observer";
+        "exact-fork": "exact-fork";
+        "exact-when-available": "exact-when-available";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"list">;
+    sourceSessionId: z.ZodString;
+    includeArchived: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"get">;
+    topicSessionId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"ask">;
+    topicSessionId: z.ZodString;
+    question: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"stop">;
+    topicSessionId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"rename">;
+    topicSessionId: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"archive">;
+    topicSessionId: z.ZodString;
+    archived: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"delete">;
+    topicSessionId: z.ZodString;
+    confirmSessionId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"models">;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"select-model">;
+    topicSessionId: z.ZodString;
+    provider: z.ZodString;
+    model: z.ZodString;
+    reasoningEffort: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>], "action">;
+export type CiteCiterRequest = z.infer<typeof citeCiterRequestSchema>;
+/** Strict response union returned by the single Remote command endpoint. */
+export declare const citeCiterResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"topic">;
+    topic: z.ZodObject<{
+        topic: z.ZodObject<{
+            topicId: z.ZodNumber;
+            sessionId: z.ZodString;
+            sourceSessionId: z.ZodString;
+            mode: z.ZodEnum<{
+                observer: "observer";
+                "exact-fork": "exact-fork";
+            }>;
+            citation: z.ZodObject<{
+                sourceSessionId: z.ZodString;
+                anchorSeq: z.ZodNumber;
+                startOffset: z.ZodNumber;
+                endOffset: z.ZodNumber;
+                sourceText: z.ZodString;
+                displayText: z.ZodString;
+                prefixText: z.ZodString;
+                suffixText: z.ZodString;
+                selectionFingerprint: z.ZodString;
+                schemaVersion: z.ZodLiteral<3>;
+                createdAt: z.ZodNumber;
+            }, z.core.$strict>;
+            title: z.ZodString;
+            titlePending: z.ZodBoolean;
+            createdAt: z.ZodNumber;
+            updatedAt: z.ZodNumber;
+            archived: z.ZodBoolean;
+            running: z.ZodBoolean;
+            sourceAvailable: z.ZodBoolean;
+            observedThroughSeq: z.ZodNullable<z.ZodNumber>;
+            modelConfig: z.ZodObject<{
+                provider: z.ZodString;
+                model: z.ZodString;
+                reasoningEffort: z.ZodOptional<z.ZodString>;
+                temperature: z.ZodOptional<z.ZodNumber>;
+                maxTokens: z.ZodOptional<z.ZodNumber>;
+                stop: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        messages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            seq: z.ZodNumber;
+            role: z.ZodEnum<{
+                error: "error";
+                user: "user";
+                assistant: "assistant";
+            }>;
+            text: z.ZodString;
+            reasoning: z.ZodNullable<z.ZodString>;
+            streaming: z.ZodBoolean;
+        }, z.core.$strict>>;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"topics">;
+    topics: z.ZodArray<z.ZodObject<{
+        topicId: z.ZodNumber;
+        sessionId: z.ZodString;
+        sourceSessionId: z.ZodString;
+        mode: z.ZodEnum<{
+            observer: "observer";
+            "exact-fork": "exact-fork";
+        }>;
+        citation: z.ZodObject<{
+            sourceSessionId: z.ZodString;
+            anchorSeq: z.ZodNumber;
+            startOffset: z.ZodNumber;
+            endOffset: z.ZodNumber;
+            sourceText: z.ZodString;
+            displayText: z.ZodString;
+            prefixText: z.ZodString;
+            suffixText: z.ZodString;
+            selectionFingerprint: z.ZodString;
+            schemaVersion: z.ZodLiteral<3>;
+            createdAt: z.ZodNumber;
+        }, z.core.$strict>;
+        title: z.ZodString;
+        titlePending: z.ZodBoolean;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+        archived: z.ZodBoolean;
+        running: z.ZodBoolean;
+        sourceAvailable: z.ZodBoolean;
+        observedThroughSeq: z.ZodNullable<z.ZodNumber>;
+        modelConfig: z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodString;
+            reasoningEffort: z.ZodOptional<z.ZodString>;
+            temperature: z.ZodOptional<z.ZodNumber>;
+            maxTokens: z.ZodOptional<z.ZodNumber>;
+            stop: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"models">;
+    providers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        models: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            reasoningEfforts: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"deleted">;
+    sessionId: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type CiteCiterResponse = z.infer<typeof citeCiterResponseSchema>;
+/** Fields whose canonical serialization defines selection identity. */
+export declare function canonicalCitationIdentity(citation: Omit<CitationDraft, 'selectionFingerprint'>): string;
+/** Render the immutable Citation as explicitly untrusted user-role context. */
+export declare function renderCitationContext(citation: CitationRecord): string;