dsh-reference-anything 0.2.0

package/lib/store/spec.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { providerSchema, settingsRecordSchema } from "../wire.js";
+export { providerSchema, settingsRecordSchema };
+export const storedAttachmentSchema = z.object({
+    attachmentId: z.string(),
+    kind: z.enum(['image', 'file']).default('file'),
+    name: z.string(),
+    mimeType: z.string(),
+    size: z.number(),
+    status: z.enum(['available', 'unavailable', 'expired']),
+    locator: z.string().optional(),
+});
+export const storedTurnSchema = z.object({
+    ordinal: z.number().int().nonnegative(),
+    messageId: z.string(),
+    parentId: z.string(),
+    branchId: z.string(),
+    role: z.enum(['user', 'assistant']),
+    text: z.string(),
+    createdAt: z.string(),
+    attachments: z.array(storedAttachmentSchema),
+});
+export const conversationRecordSchema = z.object({
+    provider: providerSchema,
+    accountScope: z.string(),
+    externalId: z.string(),
+    title: z.string(),
+    url: z.string(),
+    currentRevision: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    messageCount: z.number().int().nonnegative(),
+    partial: z.boolean(),
+    remoteMissing: z.boolean(),
+    syncedAt: z.string(),
+});
+export const revisionRecordSchema = z.object({
+    conversationKey: z.string(),
+    revision: z.string(),
+    contentHash: z.string(),
+    turnCount: z.number().int().nonnegative(),
+    activeBranch: z.string(),
+    chunkKeys: z.array(z.string()),
+    partial: z.boolean(),
+    syncedAt: z.string(),
+    expiresAt: z.string(),
+});
+export const turnChunkRecordSchema = z.object({
+    conversationKey: z.string(),
+    revision: z.string(),
+    index: z.number().int().nonnegative(),
+    turns: z.array(storedTurnSchema).max(50),
+});
+export const attachmentRecordSchema = storedAttachmentSchema.extend({
+    conversationKey: z.string(),
+    revision: z.string(),
+    ordinal: z.number().int().nonnegative(),
+});
+export const syncStateRecordSchema = z.object({
+    provider: providerSchema,
+    profile: z.string(),
+    accountScope: z.string(),
+    cursor: z.string(),
+    status: z.enum(['idle', 'running', 'cancelled', 'failed']),
+    lastSyncAt: z.string(),
+    lastCompleteScanAt: z.string(),
+    error: z.string(),
+    completed: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+    // Both carry `.default()` so rows written before background sync existed
+    // still parse at the durable read boundary — the domain validates with
+    // `schema.parse`, so the default lands in memory and no version bump (which
+    // would reject the whole medium) is needed.
+    /** Provider-level failures in a row; drives how long auto-sync skips this provider. */
+    consecutiveFailures: z.number().int().nonnegative().default(0),
+    /** ISO instant before which auto-sync leaves this provider alone. Manual syncs ignore it. */
+    nextEligibleAt: z.string().default(''),
+});
+export const referenceAnythingDomainSpec = defineDomain({
+    name: 'reference_anything',
+    version: 1,
+    global: {
+        schema: settingsRecordSchema,
+        initial: { opencliPath: 'opencli', profile: '', detailConcurrency: 8, autoSync: false, syncOnStartup: false, autoSyncMinutes: 60, historyMode: 'metadata-only', enabledProviders: [...providerSchema.options], maxReadTurns: 10, inputRenderMode: 'pill' },
+    },
+    tables: {
+        conversations: domainTable(conversationRecordSchema),
+        revisions: domainTable(revisionRecordSchema),
+        turn_chunks: domainTable(turnChunkRecordSchema),
+        attachments: domainTable(attachmentRecordSchema),
+        sync_states: domainTable(syncStateRecordSchema),
+    },
+});

package/lib/store/store.d.ts

@@ -0,0 +1,189 @@
+import type { Domain, KvTable } from '@deepseek-ai/dsh-storage-domain';
+import type { ReferenceSnapshot, ReferenceWindow } from '../types.ts';
+import type { AttachmentRecord, ChatProvider, ConversationRecord, RevisionRecord, SettingsRecord, SyncStateRecord, TurnChunkRecord } from './spec.ts';
+import type { referenceAnythingDomainSpec } from './spec.ts';
+export declare const TURNS_PER_CHUNK = 50;
+/**
+ * Shortest query that may trigger a body scan. One character matches almost
+ * every conversation, which is neither useful nor worth the scan.
+ */
+export declare const CONTENT_MIN_QUERY = 2;
+/** Conversations a single body scan may examine, newest first. */
+export declare const CONTENT_SCAN_LIMIT = 300;
+/** Characters of one conversation a body scan reads before giving up on it. */
+export declare const CONTENT_SCAN_CHARS = 200000;
+export interface ProviderConversationRow {
+    provider: ChatProvider;
+    accountScope: string;
+    id: string;
+    title: string;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+    messageCount: number;
+    cursor: string;
+    partial: boolean;
+}
+export interface ProviderTurnRow {
+    conversationId: string;
+    ordinal: number;
+    messageId: string;
+    parentId: string;
+    branchId: string;
+    activeBranch: boolean;
+    role: 'user' | 'assistant';
+    text: string;
+    createdAt: string;
+    attachmentsJson: string;
+    partial: boolean;
+}
+export interface ProviderStats {
+    provider: ChatProvider;
+    conversations: number;
+    lastSyncedAt: string;
+    status: 'ready' | 'syncing' | 'error' | 'empty';
+    error?: string;
+}
+export interface StorageStats {
+    bytes: number;
+    conversations: number;
+    remoteMissing: number;
+    oldAccountConversations: number;
+}
+/** Durable, per-provider sync status — survives page reloads, unlike any one in-flight job's status. */
+export interface ProviderSyncState {
+    provider: ChatProvider;
+    status: 'idle' | 'running' | 'cancelled' | 'failed';
+    lastSyncAt: string;
+    lastCompleteScanAt: string;
+    error: string;
+}
+/** How a conversation earned its place in a result list. */
+export type MatchedVia = 'recent' | 'title' | 'content';
+/** One scored discovery result. */
+export interface ConversationMatch {
+    readonly key: string;
+    readonly row: ConversationRecord;
+    readonly via: MatchedVia;
+    /** Excerpt around the body hit; UI-only, and present only when `via` is `content`. */
+    readonly snippet?: string;
+}
+type RefDomain = Domain<typeof referenceAnythingDomainSpec>;
+export declare class ConversationStore {
+    readonly domain: RefDomain;
+    readonly conversations: KvTable<string, ConversationRecord>;
+    readonly revisions: KvTable<string, RevisionRecord>;
+    readonly chunks: KvTable<string, TurnChunkRecord>;
+    readonly attachments: KvTable<string, AttachmentRecord>;
+    readonly syncStates: KvTable<string, SyncStateRecord>;
+    private readonly observedAccountScopes;
+    constructor(domain: RefDomain);
+    setActiveAccountScope(provider: ChatProvider, accountScope: string | undefined): void;
+    get settings(): SettingsRecord;
+    setSettings(settings: SettingsRecord): Promise<void>;
+    /** Remove every persisted transcript while retaining the title directory. */
+    clearMirrorContent(): Promise<void>;
+    static conversationKey(provider: ChatProvider, accountScope: string, externalId: string): string;
+    static parseConversationKey(key: string): [ChatProvider, string, string];
+    /**
+     * Rank conversations for a discovery surface, best match first.
+     *
+     * Three passes, each only reached when the one before it left room. Titles
+     * are matched loosely (see {@link scoreTitle}) because the `@` mention
+     * query can never contain a space; bodies are searched only when titles
+     * came up short, which is what makes the auto-generated "New chat" titles
+     * findable at all without paying for a scan on every keystroke.
+     * @param query - user query, provider prefix already stripped.
+     * @param provider - restrict to one provider.
+     * @param limit - maximum results.
+     * @returns matches, best first, capped at `limit`.
+     */
+    list(query: string, provider: ChatProvider | undefined, limit: number): ConversationMatch[];
+    stats(providers: readonly ChatProvider[]): ProviderStats[];
+    /**
+     * Search one conversation's stored turns for `pattern`.
+     *
+     * Reads chunks by key off the current revision rather than iterating the
+     * chunk table, whose `entries()` copies every record in the domain. Matching
+     * runs against the turn text in place — no lowercased copy is built, so the
+     * excerpt keeps its original casing and nothing is cached beside the
+     * records the domain already holds in memory.
+     * @returns the excerpt around the first hit, or undefined when there is none.
+     */
+    private findInBody;
+    /**
+     * Page through every stored conversation, including ones the provider no
+     * longer lists — a management view needs to surface `remoteMissing` rows
+     * so they can be cleaned up, unlike {@link list}'s mention/search surface.
+     */
+    page(query: string, provider: ChatProvider | undefined, limit: number, offset: number): {
+        items: Array<[string, ConversationRecord]>;
+        total: number;
+    };
+    /**
+     * Permanently purge one conversation and everything derived from it.
+     *
+     * A sync job racing this call can resurrect a broken row (see
+     * {@link WebChatHistoryService.remove}, which guards against that at the
+     * service layer) — this method itself makes no atomicity promise beyond
+     * "delete whatever currently references this key."
+     * @returns whether a conversation with this key existed.
+     */
+    remove(conversationKey: string): Promise<boolean>;
+    /** Approximate payload bytes held by this domain; filesystem overhead is excluded. */
+    storageStats(): StorageStats;
+    /** Permanently remove every row a complete remote scan marked as absent. */
+    removeRemoteMissing(): Promise<number>;
+    /** Permanently remove conversations and sync metadata owned by inactive accounts. */
+    removeOldAccounts(): Promise<number>;
+    removeProvider(provider: ChatProvider): Promise<number>;
+    removeOlderThan(days: number, now?: number): Promise<number>;
+    /**
+     * One row per provider, aggregated across every account scope it has ever
+     * synced under. `status`/`error`/`lastSyncAt` come from whichever attempt is
+     * most recent — success or failure — so a background failure is never
+     * hidden behind an older successful scope's row. `lastCompleteScanAt` is
+     * the max across all of that provider's rows, so it never regresses just
+     * because the latest attempt failed before finishing.
+     */
+    syncStateSummary(): ProviderSyncState[];
+    /**
+     * Record what the provider's listing says about one conversation.
+     *
+     * Skips the write when nothing but `syncedAt` would change: under the JSON
+     * storage backend a single record write re-serializes and fsyncs the entire
+     * domain, so an unchanged history would otherwise cost one whole-mirror
+     * rewrite per conversation on every pass.
+     * @returns the conversation key, written or not.
+     */
+    putConversation(row: ProviderConversationRow, accountScope: string): Promise<string>;
+    needsDetail(key: string, row: ProviderConversationRow, full: boolean): boolean;
+    /**
+     * Store one fetched transcript as an immutable revision and make it current.
+     *
+     * @param conversationKey - the conversation being updated; it must already exist.
+     * @param rows - the provider's turns, in any order.
+     * @param next - the listing row this transcript was fetched for. Supplying
+     * it folds the metadata update into the same write that publishes the
+     * revision, which is what keeps `updatedAt` — the only change signal
+     * {@link needsDetail} has — from advancing ahead of the content it describes.
+     * @returns the revision id, `sha256:<hex>` over the normalized turns.
+     */
+    commitRevision(conversationKey: string, rows: readonly ProviderTurnRow[], next?: ProviderConversationRow): Promise<string>;
+    /**
+     * Most recently observed logged-in account per provider.
+     *
+     * A non-empty account scope is written as soon as account discovery and
+     * listing complete, even if later per-conversation work fails. Older local
+     * accounts remain manageable, but must not leak back into the @ picker.
+     */
+    activeAccountScopes(): ReadonlyMap<ChatProvider, string | undefined>;
+    private oldAccountConversationKeys;
+    /** Keep exactly the latest transcript revision for a conversation. */
+    private removeSupersededRevisions;
+    read(conversationKey: string, window: ReferenceWindow): ReferenceSnapshot;
+    attachment(conversationKey: string, revision: string, attachmentId: string): AttachmentRecord | undefined;
+    markRemoteMissing(provider: ChatProvider, accountScope: string, seen: ReadonlySet<string>): Promise<void>;
+    collectExpired(now?: number): Promise<void>;
+}
+export {};