@lapis-notes/ai 0.1.0

package/dist/conversations/conversation-index.js

@@ -0,0 +1,125 @@
+export const AI_CONVERSATION_SEARCH_PROVIDER_ID = "ai-conversations";
+const INDEX_PATH_PREFIX = "ai-conversation";
+export class AiConversationIndex {
+    repository;
+    database;
+    constructor(repository, database) {
+        this.repository = repository;
+        this.database = database;
+    }
+    async sync(location) {
+        const snapshot = await this.repository.read(location);
+        const document = conversationSearchDocument(snapshot);
+        const existing = await this.database.getSearchDocument(document.path);
+        if (existing?.checksum === document.checksum)
+            return;
+        await this.database.upsertSearchDocument(document);
+    }
+    delete(location) {
+        return this.database.deleteSearchDocument(conversationIndexPath(location));
+    }
+    async search(query, limit = 100) {
+        if (!query.trim()) {
+            return (await this.repository.listAll()).slice(0, limit);
+        }
+        const results = await this.database.searchDocuments(query, {
+            sourceProviderIds: [AI_CONVERSATION_SEARCH_PROVIDER_ID],
+            mode: "lexical",
+            limit,
+        });
+        return results.flatMap((result) => {
+            const decoded = decodeConversationIndexDocument(result.document);
+            if (!decoded)
+                return [];
+            const preview = result.snippets.find((snippet) => snippet.field === "content")?.text;
+            return [{ ...decoded, ...(preview ? { preview } : {}) }];
+        });
+    }
+    async rebuild() {
+        const sourceEntries = await this.repository.listAll();
+        const sourcePaths = new Set();
+        for (const entry of sourceEntries) {
+            if (entry.unavailableReason)
+                continue;
+            try {
+                const snapshot = await this.repository.read(entry.location);
+                const document = conversationSearchDocument(snapshot);
+                sourcePaths.add(document.path);
+                await this.database.upsertSearchDocument(document);
+            }
+            catch {
+                // One unavailable conversation must not prevent history repair.
+            }
+        }
+        const indexed = (await this.database.listSearchDocuments()).filter((document) => document.sourceProviderId === AI_CONVERSATION_SEARCH_PROVIDER_ID);
+        for (const document of indexed) {
+            if (!sourcePaths.has(document.path)) {
+                await this.database.deleteSearchDocument(document.path);
+            }
+        }
+    }
+}
+export function conversationIndexPath(location) {
+    return `${INDEX_PATH_PREFIX}/${encodeURIComponent(location.scopeDir || ".")}/${location.conversationId}`;
+}
+export function conversationSearchDocument(snapshot) {
+    const content = [
+        snapshot.metadata.title,
+        ...projectSearchableTranscript(snapshot),
+    ]
+        .filter((value) => Boolean(value?.trim()))
+        .join("\n");
+    const metadataText = JSON.stringify({
+        location: snapshot.location,
+        metadata: snapshot.metadata,
+    });
+    return {
+        path: conversationIndexPath(snapshot.location),
+        sourceProviderId: AI_CONVERSATION_SEARCH_PROVIDER_ID,
+        name: snapshot.metadata.title ?? "Untitled conversation",
+        extension: "ai-conversation",
+        checksum: stableChecksum(`${content}\u0000${metadataText}`),
+        content,
+        metadataText,
+        tags: [],
+        tagParts: [],
+        tagHierarchy: [],
+    };
+}
+function projectSearchableTranscript(snapshot) {
+    return snapshot.transcript.flatMap((entry) => {
+        if (entry.type === "message" || entry.type === "thinking.summary") {
+            return [entry.text];
+        }
+        if (entry.type === "tool") {
+            return [entry.name, ...(entry.input ? [entry.input] : [])];
+        }
+        return [];
+    });
+}
+function decodeConversationIndexDocument(document) {
+    if (document.sourceProviderId !== AI_CONVERSATION_SEARCH_PROVIDER_ID ||
+        !document.metadataText) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(document.metadataText);
+        if (!parsed.location || !parsed.metadata)
+            return null;
+        return {
+            location: structuredClone(parsed.location),
+            metadata: structuredClone(parsed.metadata),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function stableChecksum(value) {
+    let hash = 2166136261;
+    for (const character of value) {
+        hash ^= character.codePointAt(0) ?? 0;
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}

package/dist/conversations/conversation-locator.d.ts

@@ -0,0 +1,2 @@
+import type { ConversationLocation } from "./types";
+export declare function relocateConversationLocation(location: ConversationLocation, oldPath: string, newPath: string): ConversationLocation | null;

package/dist/conversations/conversation-locator.js

@@ -0,0 +1,20 @@
+import { normalizePortableVaultPath } from "./paths";
+export function relocateConversationLocation(location, oldPath, newPath) {
+    const previous = normalizePortableVaultPath(oldPath, {
+        allowRoot: true,
+        label: "Previous vault path",
+    });
+    const next = normalizePortableVaultPath(newPath, {
+        allowRoot: true,
+        label: "New vault path",
+    });
+    if (location.scopeDir !== previous &&
+        !location.scopeDir.startsWith(`${previous}/`)) {
+        return null;
+    }
+    const suffix = location.scopeDir.slice(previous.length).replace(/^\//u, "");
+    return {
+        ...location,
+        scopeDir: [next, suffix].filter(Boolean).join("/"),
+    };
+}

package/dist/conversations/conversation-palette.d.ts

@@ -0,0 +1,18 @@
+import type { ConversationListEntry } from "./transcript-store";
+export declare const AI_CONVERSATION_PALETTE_TAB: {
+    readonly id: "agents";
+    readonly label: "Agents";
+    readonly order: 10;
+};
+export declare const AI_CONVERSATION_PALETTE_PROVIDER_ID = "lapis-ai-conversations";
+export declare function conversationPaletteTitle(entry: ConversationListEntry): string;
+export declare function conversationPaletteItem(entry: ConversationListEntry, now?: Date): {
+    id: string;
+    title: string;
+    subtitle: string | undefined;
+    icon: string;
+    providerId: string;
+    tab: "agents";
+    group: string;
+    trailing: string;
+};

package/dist/conversations/conversation-palette.js

@@ -0,0 +1,29 @@
+import { formatChatDateLabel, formatChatRelativeAge, } from "../chat/chat-time";
+export const AI_CONVERSATION_PALETTE_TAB = {
+    id: "agents",
+    label: "Agents",
+    order: 10,
+};
+export const AI_CONVERSATION_PALETTE_PROVIDER_ID = "lapis-ai-conversations";
+export function conversationPaletteTitle(entry) {
+    const title = entry.metadata?.title?.trim();
+    if (title)
+        return title;
+    const preview = entry.preview?.trim();
+    if (preview)
+        return preview;
+    return "Untitled chat";
+}
+export function conversationPaletteItem(entry, now = new Date()) {
+    const updatedAt = entry.metadata?.updatedAt ?? entry.metadata?.createdAt ?? "";
+    return {
+        id: `ai-conversation:${entry.location.scopeDir}:${entry.location.conversationId}`,
+        title: conversationPaletteTitle(entry),
+        subtitle: entry.location.scopeDir || entry.preview,
+        icon: "sparkles",
+        providerId: AI_CONVERSATION_PALETTE_PROVIDER_ID,
+        tab: AI_CONVERSATION_PALETTE_TAB.id,
+        group: formatChatDateLabel(updatedAt, now) || "Agents",
+        trailing: formatChatRelativeAge(updatedAt, now),
+    };
+}

package/dist/conversations/conversation-repository.d.ts

@@ -0,0 +1,39 @@
+import type { DurableSanitizationOptions } from "./redaction";
+import type { ConversationListEntry, TranscriptStore } from "./transcript-store";
+import { type AgentBindingRecord, type ConversationApprovalGrant, type ConversationLocation, type ConversationSnapshot, type TranscriptEntry } from "./types";
+export type CreateConversationInput = {
+    scopeDir: string;
+    launchNotePath?: string;
+    workspacePath?: string;
+    now?: string;
+    id?: string;
+};
+export type ConversationRepositoryChange = {
+    type: "upsert";
+    location: ConversationLocation;
+} | {
+    type: "delete";
+    location: ConversationLocation;
+};
+export declare function deriveConversationTitle(text: string): string | undefined;
+export declare class ConversationRepository {
+    private readonly store;
+    private readonly sanitization;
+    private readonly queue;
+    private readonly listeners;
+    constructor(store: TranscriptStore, sanitization?: DurableSanitizationOptions);
+    create(input: CreateConversationInput): Promise<ConversationSnapshot>;
+    read(location: ConversationLocation): Promise<ConversationSnapshot>;
+    list(scopeDir: string): Promise<ConversationListEntry[]>;
+    listAll(): Promise<ConversationListEntry[]>;
+    subscribe(listener: (change: ConversationRepositoryChange) => void): () => void;
+    appendTranscript(location: ConversationLocation, entries: TranscriptEntry[]): Promise<ConversationSnapshot>;
+    appendAgentRecords(location: ConversationLocation, records: AgentBindingRecord[]): Promise<ConversationSnapshot>;
+    writeApprovalGrants(location: ConversationLocation, grants: ConversationApprovalGrant[]): Promise<ConversationSnapshot>;
+    writePinned(location: ConversationLocation, pinned: boolean): Promise<ConversationSnapshot>;
+    archive(location: ConversationLocation, archived?: boolean): Promise<ConversationSnapshot>;
+    activateBinding(location: ConversationLocation, bindingId: string, switchEntry?: TranscriptEntry): Promise<ConversationSnapshot>;
+    delete(location: ConversationLocation): Promise<void>;
+    private emit;
+    private sanitizeEntry;
+}

package/dist/conversations/conversation-repository.js

@@ -0,0 +1,213 @@
+import { normalizeApprovalGrants } from "./approval-grants";
+import { normalizePortableVaultPath, relativePathWithinScope } from "./paths";
+import { sanitizeDurableField } from "./redaction";
+import { conversationStorageKey, ConversationWriteQueue, } from "./transcript-store";
+import { CONVERSATION_SCHEMA_VERSION, } from "./types";
+export function deriveConversationTitle(text) {
+    const normalized = text.replace(/\s+/gu, " ").trim();
+    if (!normalized)
+        return undefined;
+    return [...normalized].slice(0, 80).join("");
+}
+export class ConversationRepository {
+    store;
+    sanitization;
+    queue = new ConversationWriteQueue();
+    listeners = new Set();
+    constructor(store, sanitization = {}) {
+        this.store = store;
+        this.sanitization = sanitization;
+    }
+    async create(input) {
+        const conversationId = input.id ?? crypto.randomUUID();
+        const location = { scopeDir: input.scopeDir, conversationId };
+        const now = input.now ?? new Date().toISOString();
+        const metadata = {
+            schemaVersion: CONVERSATION_SCHEMA_VERSION,
+            id: conversationId,
+            createdAt: now,
+            updatedAt: now,
+            status: "active",
+            ...(input.launchNotePath
+                ? {
+                    launchContext: {
+                        notePath: relativePathWithinScope(input.scopeDir, input.launchNotePath),
+                    },
+                }
+                : {}),
+            ...(input.workspacePath
+                ? {
+                    workspace: {
+                        path: normalizePortableVaultPath(input.workspacePath, {
+                            allowRoot: true,
+                            label: "Workspace reference",
+                        }),
+                    },
+                }
+                : {}),
+        };
+        const snapshot = await this.store.create(location, metadata);
+        this.emit({ type: "upsert", location: snapshot.location });
+        return snapshot;
+    }
+    read(location) {
+        return this.store.read(location);
+    }
+    list(scopeDir) {
+        return this.store.list(scopeDir);
+    }
+    listAll() {
+        return this.store.listAll();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    async appendTranscript(location, entries) {
+        return this.queue.run(conversationStorageKey(location), async () => {
+            const safeEntries = entries.map((entry) => this.sanitizeEntry(entry));
+            await this.store.appendTranscriptEntries(location, safeEntries);
+            const snapshot = await this.store.read(location);
+            const firstUserMessage = snapshot.transcript.find((entry) => entry.type === "message" && entry.role === "user");
+            const title = snapshot.metadata.title ??
+                deriveConversationTitle(firstUserMessage?.type === "message" ? firstUserMessage.text : "");
+            const updatedAt = safeEntries.at(-1)?.createdAt ?? new Date().toISOString();
+            const metadata = {
+                ...snapshot.metadata,
+                ...(title ? { title } : {}),
+                updatedAt,
+            };
+            await this.store.writeMetadata(location, metadata);
+            const result = { ...snapshot, metadata };
+            this.emit({ type: "upsert", location: result.location });
+            return result;
+        });
+    }
+    async appendAgentRecords(location, records) {
+        return this.queue.run(conversationStorageKey(location), async () => {
+            await this.store.appendAgentRecords(location, records);
+            const snapshot = await this.store.read(location);
+            const updatedAt = records.at(-1)?.createdAt ?? new Date().toISOString();
+            const activeBinding = [...records]
+                .reverse()
+                .find((record) => record.type === "binding.created");
+            const metadata = {
+                ...snapshot.metadata,
+                updatedAt,
+                ...(activeBinding ? { activeAgentBindingId: activeBinding.id } : {}),
+            };
+            await this.store.writeMetadata(location, metadata);
+            const result = { ...snapshot, metadata };
+            this.emit({ type: "upsert", location: result.location });
+            return result;
+        });
+    }
+    async writeApprovalGrants(location, grants) {
+        return this.queue.run(conversationStorageKey(location), async () => {
+            const snapshot = await this.store.read(location);
+            const approvalGrants = normalizeApprovalGrants(grants);
+            const metadata = {
+                ...snapshot.metadata,
+                updatedAt: new Date().toISOString(),
+            };
+            if (approvalGrants.length > 0)
+                metadata.approvalGrants = approvalGrants;
+            else
+                delete metadata.approvalGrants;
+            await this.store.writeMetadata(location, metadata);
+            const result = { ...snapshot, metadata };
+            this.emit({ type: "upsert", location: result.location });
+            return result;
+        });
+    }
+    async writePinned(location, pinned) {
+        return this.queue.run(conversationStorageKey(location), async () => {
+            const snapshot = await this.store.read(location);
+            const metadata = {
+                ...snapshot.metadata,
+                updatedAt: new Date().toISOString(),
+            };
+            if (pinned)
+                metadata.pinned = true;
+            else
+                delete metadata.pinned;
+            await this.store.writeMetadata(location, metadata);
+            const result = { ...snapshot, metadata };
+            this.emit({ type: "upsert", location: result.location });
+            return result;
+        });
+    }
+    async archive(location, archived = true) {
+        return this.queue.run(conversationStorageKey(location), async () => {
+            const snapshot = await this.store.read(location);
+            const metadata = {
+                ...snapshot.metadata,
+                status: archived ? "archived" : "active",
+                updatedAt: new Date().toISOString(),
+            };
+            await this.store.writeMetadata(location, metadata);
+            const result = { ...snapshot, metadata };
+            this.emit({ type: "upsert", location: result.location });
+            return result;
+        });
+    }
+    async activateBinding(location, bindingId, switchEntry) {
+        return this.queue.run(conversationStorageKey(location), async () => {
+            const snapshot = await this.store.read(location);
+            const binding = snapshot.agents.find((record) => record.type === "binding.created" && record.id === bindingId);
+            if (!binding)
+                throw new Error(`Unknown agent binding: ${bindingId}`);
+            if (switchEntry) {
+                await this.store.appendTranscriptEntries(location, [
+                    this.sanitizeEntry(switchEntry),
+                ]);
+            }
+            const metadata = {
+                ...snapshot.metadata,
+                activeAgentBindingId: bindingId,
+                updatedAt: switchEntry?.createdAt ?? new Date().toISOString(),
+            };
+            await this.store.writeMetadata(location, metadata);
+            const result = await this.store.read(location);
+            this.emit({ type: "upsert", location: result.location });
+            return result;
+        });
+    }
+    async delete(location) {
+        await this.store.delete(location);
+        this.emit({ type: "delete", location: { ...location } });
+    }
+    emit(change) {
+        for (const listener of this.listeners)
+            listener(change);
+    }
+    sanitizeEntry(entry) {
+        if (entry.type === "tool") {
+            const input = sanitizeDurableField(entry.input, this.sanitization);
+            const output = sanitizeDurableField(entry.output, this.sanitization);
+            return {
+                ...entry,
+                input: input.text,
+                output: output.text,
+                redacted: entry.redacted || input.redacted || output.redacted || undefined,
+                truncated: entry.truncated || input.truncated || output.truncated || undefined,
+            };
+        }
+        if (entry.type === "approval.request" && entry.tool?.input) {
+            const input = sanitizeDurableField(entry.tool.input, this.sanitization);
+            return {
+                ...entry,
+                tool: { ...entry.tool, input: input.text },
+                redacted: entry.redacted || input.redacted || undefined,
+                truncated: entry.truncated || input.truncated || undefined,
+            };
+        }
+        if (entry.type === "error") {
+            return {
+                ...entry,
+                message: sanitizeDurableField(entry.message, this.sanitization).text ?? "",
+            };
+        }
+        return entry;
+    }
+}

package/dist/conversations/handoff-summary.d.ts

@@ -0,0 +1,48 @@
+import type { AgentRequest, AgentRuntime } from "../core/types";
+import type { ConversationRepository } from "./conversation-repository";
+import { type ConversationLocation } from "./types";
+export type GroundedHandoffSummaryInput = {
+    conversationId: string;
+    fromEntryId: string;
+    throughEntryId: string;
+    sourceHash: string;
+    entries: Array<{
+        id: string;
+        hash: string;
+        type: string;
+        role?: "user" | "assistant";
+        agentBindingId?: string;
+        content: string;
+    }>;
+};
+export interface HandoffSummaryProvider {
+    propose(input: GroundedHandoffSummaryInput, signal?: AbortSignal): Promise<{
+        summary: string;
+    }>;
+}
+export type HandoffSummaryProcessorIdentity = {
+    runtime: "acp" | "codex-native";
+    agent: "codex" | "cursor";
+    model: string;
+};
+export declare class HandoffSummaryCoordinator {
+    #private;
+    private readonly repository;
+    private readonly provider;
+    private readonly processor;
+    private readonly enabled;
+    constructor(repository: ConversationRepository, provider: HandoffSummaryProvider, processor: HandoffSummaryProcessorIdentity | (() => HandoffSummaryProcessorIdentity), enabled?: () => boolean);
+    afterTerminal(location: ConversationLocation): Promise<void>;
+}
+export type RuntimeHandoffSummaryProviderOptions = {
+    configuration: () => HandoffSummaryProcessorIdentity;
+    resolveRuntime: (request: AgentRequest) => Promise<AgentRuntime>;
+    timeoutMs?: number;
+};
+export declare class RuntimeHandoffSummaryProvider implements HandoffSummaryProvider {
+    private readonly options;
+    constructor(options: RuntimeHandoffSummaryProviderOptions);
+    propose(input: GroundedHandoffSummaryInput, signal?: AbortSignal): Promise<{
+        summary: string;
+    }>;
+}