@dev-sergeev/datalab-kit 0.1.2 → 0.1.3

package/node_modules/@zigai/pi-mention-anything/src/mention-hub.ts

@@ -0,0 +1,307 @@
+import type { ContextEvent, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+    createChainAutocompleteProvider,
+    type ChainCompletionSource,
+} from "./chain-autocomplete.ts";
+import { parseMentions } from "./chain-syntax.ts";
+import { applyMentionEditor, createMentionContinuation } from "./editor.ts";
+import {
+    createMentionExpansion,
+    createMentionSelections,
+    type ExpansionSource,
+    type MentionSnapshot,
+} from "./mention-resolution.ts";
+import type { MentionRegistration } from "./register-mention.ts";
+import { createSourceRuntime, type SourceRuntime } from "./source-runtime.ts";
+
+const MENTION_HUB_PROTOCOL_VERSION = 2;
+const MENTION_HUB_PROTOCOL = Symbol.for("zigai.pi-mention-anything.hub-protocol-version");
+const MENTION_HUB = Symbol.for("zigai.pi-mention-anything.hub");
+
+export type MentionHub = {
+    readonly [MENTION_HUB_PROTOCOL]: typeof MENTION_HUB_PROTOCOL_VERSION;
+    add(registration: MentionRegistration): symbol;
+    remove(handle: symbol): Promise<void>;
+    input(text: string): void;
+
+    context(
+        messages: ContextEvent["messages"],
+        signal?: AbortSignal,
+    ): Promise<ContextEvent["messages"]>;
+};
+
+type UnknownDataDescriptor = Omit<PropertyDescriptor, "value"> & { readonly value: unknown };
+
+function isUnknownDataDescriptor(
+    descriptor: PropertyDescriptor | undefined,
+): descriptor is UnknownDataDescriptor {
+    return descriptor !== undefined && Object.hasOwn(descriptor, "value");
+}
+
+// oxlint-disable-next-line antislop/no-object-parameters -- Protocol data may be attached to any Pi UI or hub object.
+function getOwnDataDescriptor(target: object, key: PropertyKey): UnknownDataDescriptor | undefined {
+    const descriptor = Object.getOwnPropertyDescriptor(target, key);
+    if (!isUnknownDataDescriptor(descriptor)) return undefined;
+    return descriptor;
+}
+
+function isNonNullObject(value: unknown): value is object {
+    return typeof value === "object" && value !== null;
+}
+
+function isNumber(value: unknown): value is number {
+    return typeof value === "number";
+}
+
+// oxlint-disable-next-line antislop/no-object-parameters -- Hub records are intentionally structural protocol objects.
+function hasOwnFunctionProperty(target: object, key: PropertyKey): boolean {
+    return typeof getOwnDataDescriptor(target, key)?.value === "function";
+}
+
+/** Reads protocol data shared by independently loaded copies in the same Pi UI session. */
+function readHub(ui: ExtensionContext["ui"]): MentionHub | undefined {
+    const descriptor = getOwnDataDescriptor(ui, MENTION_HUB);
+    if (descriptor === undefined) return undefined;
+    if (!isNonNullObject(descriptor.value)) throw new TypeError("Incompatible mention hub");
+
+    const hub = descriptor.value;
+    const version = getOwnDataDescriptor(hub, MENTION_HUB_PROTOCOL)?.value;
+    if (version !== MENTION_HUB_PROTOCOL_VERSION) {
+        let versionLabel = Object.prototype.toString.call(version).slice(8, -1).toLowerCase();
+        if (isNumber(version)) versionLabel = version.toString();
+        throw new TypeError(`Unsupported mention hub protocol version ${versionLabel}`);
+    }
+
+    if (
+        !hasOwnFunctionProperty(hub, "add") ||
+        !hasOwnFunctionProperty(hub, "remove") ||
+        !hasOwnFunctionProperty(hub, "input") ||
+        !hasOwnFunctionProperty(hub, "context")
+    ) {
+        throw new TypeError("Incompatible mention hub");
+    }
+
+    // SAFETY: Version and structural checks validate the runtime protocol shared across
+    // independently loaded module copies. The UI object fixes the session scope.
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- SAFETY: The versioned structural protocol is validated above.
+    return hub as MentionHub;
+}
+
+function createHub(ctx: ExtensionContext): MentionHub {
+    const ui = ctx.ui;
+    const runtimes = new Map<string, SourceRuntime>();
+    const handles = new Map<symbol, SourceRuntime>();
+    const sources: (ChainCompletionSource & ExpansionSource)[] = [];
+    const selections = createMentionSelections();
+    const expansion = createMentionExpansion();
+    const continuation = createMentionContinuation();
+    let pendingSnapshots: readonly MentionSnapshot[] = [];
+    let pendingText = "";
+    let editor: ReturnType<typeof applyMentionEditor> | undefined;
+    let autocompleteInstalled = false;
+    let autocomplete: ReturnType<typeof createChainAutocompleteProvider> | undefined;
+    let activeWarmups = 0;
+    const pendingWarmups: SourceRuntime[] = [];
+    const warmNext = (): void => {
+        while (activeWarmups < 4 && pendingWarmups.length > 0) {
+            const runtime = pendingWarmups.shift();
+            if (runtime === undefined || runtimes.get(runtime.id) !== runtime) continue;
+            activeWarmups += 1;
+
+            // The hub bounds startup work; each controller owns cancellation and safe diagnostics.
+            void runtime.controller
+                .warm()
+                .catch(() => {})
+                .finally(() => {
+                    activeWarmups -= 1;
+                    warmNext();
+                });
+        }
+    };
+
+    let unresolved = new Set<string>();
+    const processedContexts = new WeakSet<
+        Parameters<ReturnType<typeof createMentionExpansion>["messages"]>[0]
+    >();
+
+    const hub: MentionHub = {
+        [MENTION_HUB_PROTOCOL]: MENTION_HUB_PROTOCOL_VERSION,
+        add(registration: MentionRegistration): symbol {
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(registration.id))
+                throw new Error("Mention registration ID must be lowercase kebab-case.");
+
+            const configuration = registration.configuration(ctx);
+
+            if (
+                runtimes.has(registration.id) ||
+                sources.some((source) => source.trigger === configuration.trigger)
+            ) {
+                throw new Error(
+                    "Mention sources require unique IDs and triggers within a session.",
+                );
+            }
+
+            if (!configuration.trigger || /[\s/]/.test(configuration.trigger))
+                throw new Error("Invalid mention trigger.");
+
+            if (
+                configuration.separator !== undefined &&
+                (configuration.separator.length !== 1 || /[\s"\\\\]/.test(configuration.separator))
+            )
+                throw new Error(
+                    "Mention separator must be one non-whitespace character other than quote or backslash.",
+                );
+
+            const runtime = createSourceRuntime(ctx, registration, configuration);
+            const handle = Symbol(registration.id);
+            handles.set(handle, runtime);
+
+            const source = runtime.source;
+            runtimes.set(registration.id, runtime);
+            sources.push(source);
+
+            if (ctx.hasUI && !autocompleteInstalled) {
+                autocompleteInstalled = true;
+                editor = applyMentionEditor(ctx, {
+                    key: Symbol.for("zigai.pi-mention-anything.engine.editor"),
+                    continuation,
+                    onTextChange: (text) => {
+                        selections.reconcile(text);
+                        autocomplete?.reconcile(text);
+                    },
+                    onSubmitText: (text) => hub.input(text),
+                    isMentionContext: (line) =>
+                        parseMentions(line, sources).some((span) => span.end === line.length),
+                    colorLine: (line) => {
+                        let colored = "";
+                        let offset = 0;
+                        for (const span of parseMentions(line, sources)) {
+                            colored += line.slice(offset, span.start);
+
+                            let color: "accent" | "warning" = "accent";
+                            if (!span.complete || unresolved.has(span.sourceId)) color = "warning";
+                            colored += ctx.ui.theme.fg(color, line.slice(span.start, span.end));
+                            offset = span.end;
+                        }
+
+                        return colored + line.slice(offset);
+                    },
+                });
+                ctx.ui.addAutocompleteProvider((current) => {
+                    autocomplete?.dispose();
+                    autocomplete = createChainAutocompleteProvider({
+                        current,
+                        sources,
+                        onContinue: () => continuation.request(),
+                        resolveSelected: (sourceId, segments, start) =>
+                            selections
+                                .snapshot(ui.getEditorText())
+                                .find(
+                                    (snapshot) =>
+                                        snapshot.sourceId === sourceId &&
+                                        snapshot.start === start &&
+                                        segments.every(
+                                            (segment, index) =>
+                                                snapshot.path[index]?.segment === segment,
+                                        ),
+                                )
+                                ?.path.slice(0, segments.length),
+                        onState: (sourceId, status) => {
+                            if (status === "ready") unresolved.delete(sourceId);
+                            else unresolved.add(sourceId);
+                        },
+                        onSelection: (selection) => {
+                            selections.record(selection, selection.editorText);
+                            runtimes
+                                .get(selection.sourceId)
+                                ?.history.recordSelection(
+                                    JSON.stringify(selection.path.map((candidate) => candidate.id)),
+                                );
+                        },
+                    });
+
+                    return autocomplete;
+                });
+            }
+
+            pendingWarmups.push(runtime);
+            warmNext();
+
+            return handle;
+        },
+        async remove(handle: symbol): Promise<void> {
+            const runtime = handles.get(handle);
+            if (runtime === undefined) return;
+
+            handles.delete(handle);
+            runtimes.delete(runtime.id);
+
+            const index = sources.indexOf(runtime.source);
+            if (index !== -1) sources.splice(index, 1);
+            await Promise.all([runtime.controller.dispose(), runtime.history.flush()]);
+
+            if (runtimes.size === 0) {
+                autocomplete?.dispose();
+                autocomplete = undefined;
+                editor?.dispose();
+                editor = undefined;
+                expansion.clear();
+                selections.clear();
+
+                if (
+                    getOwnDataDescriptor(ui, MENTION_HUB)?.value === hub &&
+                    !Reflect.deleteProperty(ui, MENTION_HUB)
+                ) {
+                    throw new TypeError("Unable to remove the shared mention hub");
+                }
+            }
+        },
+        input(text: string): void {
+            if (pendingText === text && pendingSnapshots.length > 0) return;
+
+            pendingText = text;
+            pendingSnapshots = selections.snapshot(text);
+        },
+        async context(
+            messages: Parameters<ReturnType<typeof createMentionExpansion>["messages"]>[0],
+            signal?: AbortSignal,
+        ) {
+            if (processedContexts.has(messages)) return messages;
+
+            unresolved = new Set();
+
+            const result = await expansion.messages(messages, sources, {
+                signal,
+                snapshots: pendingSnapshots,
+                onUnresolved: (id) => {
+                    unresolved.add(id);
+                },
+            });
+
+            pendingSnapshots = [];
+            pendingText = "";
+            processedContexts.add(result);
+
+            return result;
+        },
+    };
+
+    return hub;
+}
+
+export function sharedHub(ctx: ExtensionContext): MentionHub {
+    const existing = readHub(ctx.ui);
+    if (existing !== undefined) return existing;
+
+    const hub = createHub(ctx);
+    if (
+        !Reflect.defineProperty(ctx.ui, MENTION_HUB, {
+            configurable: true,
+            value: hub,
+        })
+    ) {
+        throw new TypeError("Unable to store the shared mention hub");
+    }
+
+    return hub;
+}

package/node_modules/@zigai/pi-mention-anything/src/mention-resolution.ts

@@ -0,0 +1,374 @@
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+
+import { isTriggerBoundary, parseMentions } from "./chain-syntax.ts";
+import type { Candidate, Resolution } from "./source-contract.ts";
+
+export type MentionSnapshot = {
+    readonly sourceId: string;
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+    readonly path: readonly Candidate[];
+};
+
+export type ExpansionSource = {
+    readonly id: string;
+    readonly trigger: string;
+    readonly separator?: string;
+    readonly expansionPolicy?: "selected-only" | "selected-or-resolved";
+    readonly replacementTemplate?: string;
+    readonly resolve: (segments: readonly string[], signal?: AbortSignal) => Promise<Resolution>;
+
+    readonly replacement?: (
+        path: readonly Candidate[],
+        options: { readonly signal?: AbortSignal },
+    ) => string | Promise<string>;
+};
+
+export type MentionSelections = {
+    reconcile(text: string): void;
+    record(snapshot: MentionSnapshot, editorText: string): void;
+    snapshot(text: string): readonly MentionSnapshot[];
+    clear(): void;
+};
+
+/** Snapshots belong to exact editor occurrences. Edits overlapping one discard it. */
+export function createMentionSelections(): MentionSelections {
+    let previousText = "";
+    let snapshots: MentionSnapshot[] = [];
+    const reconcile = (text: string): void => {
+        if (text === previousText) return;
+
+        let prefix = 0;
+        while (
+            prefix < text.length &&
+            prefix < previousText.length &&
+            text[prefix] === previousText[prefix]
+        )
+            prefix += 1;
+
+        let suffix = 0;
+        while (
+            suffix < text.length - prefix &&
+            suffix < previousText.length - prefix &&
+            text[text.length - 1 - suffix] === previousText[previousText.length - 1 - suffix]
+        )
+            suffix += 1;
+
+        const oldEnd = previousText.length - suffix;
+        const delta = text.length - previousText.length;
+        let changedText = text.slice(prefix, text.length - suffix);
+        if (delta < 0) changedText = previousText.slice(prefix, oldEnd);
+
+        const ambiguous = new Set(
+            snapshots
+                .filter(
+                    (snapshot) =>
+                        delta !== 0 &&
+                        snapshot.end === prefix &&
+                        changedText.includes(snapshot.text),
+                )
+                .map((snapshot) => snapshot.text),
+        );
+
+        snapshots = snapshots
+            .flatMap((snapshot) => {
+                if (ambiguous.has(snapshot.text)) return [];
+                if (snapshot.end <= prefix) return [snapshot];
+
+                if (snapshot.start >= oldEnd)
+                    return [
+                        { ...snapshot, start: snapshot.start + delta, end: snapshot.end + delta },
+                    ];
+
+                return [];
+            })
+            .filter((snapshot) => {
+                if (text.slice(snapshot.start, snapshot.end) !== snapshot.text) return false;
+                if (!isTriggerBoundary(text, snapshot.start)) return false;
+
+                const adjacent = /^\S*/.exec(text.slice(snapshot.end))?.[0] ?? "";
+                return /^[.,;!?)}\]]*$/.test(adjacent);
+            });
+        previousText = text;
+    };
+
+    return {
+        reconcile,
+        record(snapshot: MentionSnapshot, editorText: string): void {
+            reconcile(editorText);
+            snapshots = snapshots.filter(
+                (existing) => existing.end <= snapshot.start || existing.start >= snapshot.end,
+            );
+            snapshots.push({ ...snapshot, path: structuredClone(snapshot.path) });
+        },
+        snapshot(text: string): readonly MentionSnapshot[] {
+            reconcile(text);
+
+            return snapshots.map((snapshot) => ({
+                ...snapshot,
+                path: structuredClone(snapshot.path),
+            }));
+        },
+        clear(): void {
+            previousText = "";
+            snapshots = [];
+        },
+    };
+}
+
+/** Declarative fields only: no property traversal or provider-data serialization. */
+export function renderReplacementTemplate(template: string, path: readonly Candidate[]): string {
+    const target = path.at(-1);
+    if (target === undefined) throw new Error("Cannot render an empty mention target.");
+
+    const fields = new Map<string, string>([
+        ["id", target.id],
+        ["label", target.label],
+        ["segment", target.segment],
+        ["path", path.map((candidate) => candidate.segment).join(":")],
+        ["ids", path.map((candidate) => candidate.id).join(":")],
+    ]);
+
+    return template.replace(/\{\{\s*([^{}]+?)\s*\}\}/g, (_match: string, field: string) => {
+        const value = fields.get(field);
+        if (value === undefined)
+            throw new Error("Mention replacement template contains an undeclared field.");
+
+        return value;
+    });
+}
+
+export async function expandMentionText(
+    text: string,
+    sources: readonly ExpansionSource[],
+    options: {
+        readonly snapshots?: readonly MentionSnapshot[];
+        readonly signal?: AbortSignal;
+        readonly onUnresolved?: (sourceId: string) => void;
+    } = {},
+): Promise<string> {
+    const selectedSpans = (options.snapshots ?? []).filter(
+        (snapshot) =>
+            text.slice(snapshot.start, snapshot.end) === snapshot.text &&
+            sources.some((source) => source.id === snapshot.sourceId),
+    );
+    const spans = [
+        ...parseMentions(text, sources).filter(
+            (span) =>
+                !selectedSpans.some(
+                    (snapshot) => snapshot.start < span.end && snapshot.end > span.start,
+                ),
+        ),
+        ...selectedSpans.map((snapshot) => ({
+            ...snapshot,
+            complete: true,
+            segments: snapshot.path.map((candidate) => candidate.segment),
+        })),
+    ].sort((left, right) => left.start - right.start);
+    let result = "";
+    let offset = 0;
+
+    // Bounded sequential resolution avoids command bursts in a large pasted prompt.
+    for (const span of spans) {
+        options.signal?.throwIfAborted();
+        result += text.slice(offset, span.start);
+        offset = span.end;
+
+        const literal = text.slice(span.start, span.end);
+        const source = sources.find((candidate) => candidate.id === span.sourceId);
+        if (!span.complete || source === undefined) {
+            result += literal;
+            continue;
+        }
+
+        const selected = options.snapshots?.find(
+            (snapshot) =>
+                snapshot.sourceId === source.id &&
+                snapshot.start === span.start &&
+                snapshot.end === span.end &&
+                snapshot.text === literal,
+        );
+        let resolution: Resolution;
+        if (selected !== undefined) resolution = { status: "resolved", path: selected.path };
+        else if (source.expansionPolicy === "selected-only") {
+            result += literal;
+            continue;
+        } else {
+            try {
+                resolution = await source.resolve(span.segments, options.signal);
+            } catch {
+                options.signal?.throwIfAborted();
+                result += literal;
+                options.onUnresolved?.(source.id);
+                continue;
+            }
+        }
+
+        if (resolution.status !== "resolved") {
+            result += literal;
+            options.onUnresolved?.(source.id);
+            continue;
+        }
+
+        const target = resolution.path.at(-1);
+        if (target === undefined || !target.selectable) {
+            result += literal;
+            options.onUnresolved?.(source.id);
+            continue;
+        }
+
+        try {
+            let replacement = resolution.replacement ?? target.replacement ?? target.segment;
+            if (source.replacement !== undefined) {
+                replacement = await source.replacement(resolution.path, { signal: options.signal });
+            } else if (source.replacementTemplate !== undefined) {
+                replacement = renderReplacementTemplate(
+                    source.replacementTemplate,
+                    resolution.path,
+                );
+            }
+
+            result += replacement;
+        } catch {
+            options.signal?.throwIfAborted();
+            result += literal;
+            options.onUnresolved?.(source.id);
+        }
+    }
+
+    return result + text.slice(offset);
+}
+
+/** One pass over original user blocks. Memoized submissions survive context rebuilds/retries. */
+export type MentionExpansion = {
+    messages(
+        messages: ContextEvent["messages"],
+        sources: readonly ExpansionSource[],
+        options?: {
+            readonly signal?: AbortSignal;
+            readonly snapshots?: readonly MentionSnapshot[];
+            readonly onUnresolved?: (sourceId: string) => void;
+        },
+    ): Promise<ContextEvent["messages"]>;
+
+    clear(): void;
+};
+
+export function createMentionExpansion(): MentionExpansion {
+    const submissions = new Map<string, string>();
+    const processed = new WeakSet<ContextEvent["messages"]>();
+    const remember = (key: string, value: string): void => {
+        submissions.set(key, value);
+    };
+
+    return {
+        async messages(
+            messages: ContextEvent["messages"],
+            sources: readonly ExpansionSource[],
+            options: {
+                readonly signal?: AbortSignal;
+                readonly snapshots?: readonly MentionSnapshot[];
+                readonly onUnresolved?: (sourceId: string) => void;
+            } = {},
+        ): Promise<ContextEvent["messages"]> {
+            if (processed.has(messages)) return messages;
+
+            let changed = false;
+            const activeKeys = new Set<string>();
+            const expanded: ContextEvent["messages"] = [];
+            let latestUser = -1;
+            for (let index = messages.length - 1; index >= 0; index -= 1) {
+                if (messages[index]?.role !== "user") continue;
+                latestUser = index;
+                break;
+            }
+
+            for (const [messageIndex, message] of messages.entries()) {
+                if (message.role !== "user") {
+                    expanded.push(message);
+                    continue;
+                }
+
+                let firstTextBlock = 0;
+                if (Array.isArray(message.content)) {
+                    firstTextBlock = message.content.findIndex((block) => block.type === "text");
+                }
+
+                const expandBlock = async (text: string, block: number): Promise<string> => {
+                    const key = JSON.stringify([message.timestamp, block, text]);
+                    activeKeys.add(key);
+
+                    const cached = submissions.get(key);
+                    if (cached !== undefined) {
+                        activeKeys.add(JSON.stringify([message.timestamp, block, cached]));
+                        return cached;
+                    }
+
+                    let snapshots: readonly MentionSnapshot[] | undefined;
+                    if (messageIndex === latestUser && block === firstTextBlock) {
+                        snapshots = options.snapshots;
+                    }
+
+                    const value = await expandMentionText(text, sources, {
+                        ...options,
+                        snapshots,
+                    });
+                    remember(key, value);
+
+                    // A subsequent context handler must not reinterpret generated text.
+                    const generatedKey = JSON.stringify([message.timestamp, block, value]);
+                    remember(generatedKey, value);
+                    activeKeys.add(generatedKey);
+
+                    return value;
+                };
+                if (!Array.isArray(message.content)) {
+                    const content = await expandBlock(message.content, 0);
+                    changed ||= content !== message.content;
+
+                    if (content === message.content) expanded.push(message);
+                    else expanded.push({ ...message, content });
+                } else {
+                    let blockChanged = false;
+                    const content: typeof message.content = [];
+                    for (const [index, block] of message.content.entries()) {
+                        if (block.type !== "text") {
+                            content.push(block);
+                            continue;
+                        }
+
+                        const text = await expandBlock(block.text, index);
+                        blockChanged ||= text !== block.text;
+
+                        if (text === block.text) content.push(block);
+                        else content.push({ ...block, text });
+                    }
+
+                    changed ||= blockChanged;
+
+                    if (blockChanged) expanded.push({ ...message, content });
+                    else expanded.push(message);
+                }
+            }
+
+            // Keep all active-context resolutions; only the historical tail is bounded.
+            let historical = submissions.size - activeKeys.size;
+            for (const key of submissions.keys()) {
+                if (historical <= 512) break;
+                if (activeKeys.has(key)) continue;
+                submissions.delete(key);
+                historical -= 1;
+            }
+
+            let result = messages;
+            if (changed) result = expanded;
+            processed.add(result);
+
+            return result;
+        },
+        clear(): void {
+            submissions.clear();
+        },
+    };
+}