@qvac/harness 1.0.0-rc.0 → 1.0.0-rc.2

package/dist-lib/plugins/image/index.js

@@ -0,0 +1,76 @@
+import { retryMemo } from '../../lib/helpers/retry-memo.js';
+import { PluginRegistry } from '../../lib/plugins/index.js';
+import { createEditImageTool, loadMediaCodecs } from './edit-image.js';
+import { createDiffusionRuntime, createGenerateImageTool } from './generate-image.js';
+export { createEditImageTool } from './edit-image.js';
+export { createDiffusionRuntime, createGenerateImageTool, generationPercentTick, IMAGE_LOAD_STALL_ERROR, settingsDimension, settingsSteps } from './generate-image.js';
+const BUSY_MESSAGE = 'the chat model is busy; try the image again once the current reply finishes';
+function diffusionRuntime(models, model) {
+    const loadSdk = retryMemo(async () => {
+        const sdk = await models.sdk();
+        const [{ diffusionPlugin }, { registerPlugin }] = await Promise.all([
+            import('@qvac/sdk/sdcpp-generation/plugin'),
+            import('@qvac/sdk/plugins')
+        ]);
+        try {
+            registerPlugin(diffusionPlugin);
+        }
+        catch { }
+        return sdk;
+    });
+    const transfers = new Map();
+    return createDiffusionRuntime({
+        ...(typeof model === 'string' ? { model } : model),
+        loads: models,
+        loadSdk,
+        onProgress: (name, progress) => {
+            const state = models.progressState(name, progress);
+            if (state.status === 'downloading' &&
+                typeof progress.percentage === 'number' &&
+                progress.percentage < 100) {
+                transfers.set(name, state);
+            }
+            models.emit(state.status === 'downloading' && !transfers.has(name)
+                ? { ...state, status: 'loading' }
+                : state);
+        },
+        onLoaded: (name) => {
+            const transfer = transfers.get(name);
+            if (!transfer) {
+                return;
+            }
+            transfers.delete(name);
+            models.statusChanged();
+            models.emit({ ...transfer, status: 'downloaded' });
+        },
+        onBeforeLoad: (signal) => models.makeRoom(signal, BUSY_MESSAGE)
+    });
+}
+export class Image {
+    name = 'image';
+    api = PluginRegistry.API_VERSION;
+    needs = ['models'];
+    addons = {
+        'diffusion-cpp': () => import('@qvac/diffusion-cpp/addonLogging'),
+        'bare-image-resample': () => import('bare-image-resample'),
+        'bare-media': loadMediaCodecs
+    };
+    read;
+    _options;
+    constructor(options) {
+        this._options = options;
+        this.read = options.read;
+    }
+    validate() {
+        return this._options.model ? null : 'needs a model';
+    }
+    setup(ctx) {
+        const { model, clamps } = this._options;
+        const runtime = diffusionRuntime(ctx.service('models'), model);
+        return {
+            tools: [createGenerateImageTool(runtime, clamps), createEditImageTool(runtime, {}, clamps)],
+            unload: () => runtime.unload(),
+            unloadIdle: () => runtime.unloadIdle()
+        };
+    }
+}

package/dist-lib/plugins/knowledge/index.d.ts

@@ -0,0 +1,21 @@
+import type { HarnessPlugin, PluginContext, PluginSetup } from '../../lib/plugins/index.ts';
+export { KNOWLEDGE_SEARCH_TOOL } from './search-tool.ts';
+export interface KnowledgeOptions {
+    dir: string;
+    model: string;
+    maxChunks?: number;
+    minScore?: number;
+    tool?: boolean;
+    read?: readonly string[];
+}
+export declare class Knowledge implements HarnessPlugin {
+    readonly name = "knowledge";
+    readonly api = 1;
+    readonly provides: string[];
+    readonly needs: string[];
+    readonly read: readonly string[] | undefined;
+    private readonly _options;
+    constructor(options: KnowledgeOptions);
+    validate(): string | null;
+    setup(ctx: PluginContext): PluginSetup;
+}

package/dist-lib/plugins/knowledge/index.js

@@ -0,0 +1,47 @@
+import { PluginRegistry } from '../../lib/plugins/index.js';
+import { knowledgeSearchTool } from './search-tool.js';
+import { KnowledgeStore } from './store.js';
+export { KNOWLEDGE_SEARCH_TOOL } from './search-tool.js';
+function invalid(config) {
+    if (!config?.dir || !config.model) {
+        return 'needs a dir and an embedding model';
+    }
+    const { maxChunks } = config;
+    if (maxChunks !== undefined && !(Number.isSafeInteger(maxChunks) && maxChunks > 0)) {
+        return 'maxChunks must be a positive integer';
+    }
+    if (config.minScore !== undefined && !Number.isFinite(config.minScore)) {
+        return 'minScore must be a number';
+    }
+    return null;
+}
+export class Knowledge {
+    name = 'knowledge';
+    api = PluginRegistry.API_VERSION;
+    provides = ['knowledge'];
+    needs = ['embed'];
+    read;
+    _options;
+    constructor(options) {
+        this._options = options;
+        this.read = options?.read;
+    }
+    validate() {
+        return invalid(this._options);
+    }
+    setup(ctx) {
+        const config = this._options;
+        const store = new KnowledgeStore({
+            dir: config.dir,
+            model: config.model,
+            maxChunks: config.maxChunks,
+            minScore: config.minScore,
+            embed: ctx.service('embed')
+        });
+        return {
+            services: { knowledge: store },
+            tools: config.tool ? [knowledgeSearchTool(store)] : [],
+            teardown: () => store.close()
+        };
+    }
+}

package/dist-lib/plugins/knowledge/search-tool.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from '../../lib/contract/index.ts';
+import type { KnowledgeService } from '../../lib/contract/knowledge.ts';
+export declare const KNOWLEDGE_SEARCH_TOOL = "knowledge_search";
+export declare function knowledgeSearchTool(knowledge: KnowledgeService): ToolDefinition;

package/dist-lib/plugins/knowledge/search-tool.js

@@ -0,0 +1,38 @@
+export const KNOWLEDGE_SEARCH_TOOL = 'knowledge_search';
+export function knowledgeSearchTool(knowledge) {
+    return {
+        name: KNOWLEDGE_SEARCH_TOOL,
+        toolset: 'knowledge',
+        autoApprove: true,
+        description: 'Search the knowledge shared with this conversation: files, documents and past chats. ' +
+            'Use it when the answer may be in them and the passages already given do not have it.',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'What to look for, in your own words: "the deadline in the lease"'
+                }
+            },
+            required: ['query']
+        },
+        effect: () => 'read',
+        async execute(args, ctx) {
+            const query = typeof args.query === 'string' ? args.query.trim() : '';
+            if (!query) {
+                return { error: 'query must be a non-empty string' };
+            }
+            const scopes = ctx?.knowledge?.scopes ?? [];
+            const hits = scopes.length
+                ? await knowledge.search({ text: query, scopes, signal: ctx?.signal })
+                : [];
+            return {
+                results: hits.map(({ artifactId, chunkId, text }) => ({
+                    source: artifactId,
+                    chunkId,
+                    text
+                }))
+            };
+        }
+    };
+}

package/dist-lib/plugins/knowledge/store.d.ts

@@ -0,0 +1,42 @@
+import type { KnowledgeArtifact, KnowledgeHit, KnowledgeQuery, KnowledgeRemoved, KnowledgeService, KnowledgeStatus, KnowledgeUpsertResult } from '../../lib/contract/knowledge.ts';
+import type { EmbedHost } from '../../lib/contract/models.ts';
+export interface KnowledgeStoreOptions {
+    dir: string;
+    model: string;
+    maxChunks?: number;
+    minScore?: number;
+    embed: EmbedHost;
+}
+export declare class KnowledgeStore implements KnowledgeService {
+    private readonly _dir;
+    private readonly _model;
+    private readonly _maxChunks;
+    private readonly _minScore;
+    private readonly _embed;
+    private _manifest;
+    private _index;
+    private _opened;
+    private _lane;
+    constructor({ dir, model, maxChunks, minScore, embed }: KnowledgeStoreOptions);
+    upsert(artifact: KnowledgeArtifact): Promise<KnowledgeUpsertResult>;
+    remove(artifactId: string): Promise<KnowledgeRemoved>;
+    search(query: KnowledgeQuery): Promise<KnowledgeHit[]>;
+    status(): Promise<KnowledgeStatus>;
+    close(): Promise<void>;
+    private _serial;
+    private _recovering;
+    private _open;
+    private _rebuild;
+    private _unload;
+    private _upsert;
+    private _add;
+    private _embedChunks;
+    private _indexFor;
+    private _drop;
+    private _evict;
+    private _search;
+    private _chunksById;
+    private _chunkCount;
+    private _file;
+    private _persist;
+}

package/dist-lib/plugins/knowledge/store.js

@@ -0,0 +1,332 @@
+import fs from 'fs';
+import path from 'path';
+import { isRecord } from '../../lib/guards.js';
+const INDEX_FILE = 'knowledge.qvi';
+const MANIFEST_FILE = 'knowledge.json';
+const DEFAULT_K = 5;
+const DEFAULT_MIN_SCORE = 0.4;
+const VECTOR_INDEX_NOT_FOUND = 52851;
+function emptyManifest(model) {
+    return { model, dimensions: 0, nextId: 1, seq: 0, artifacts: {} };
+}
+function isManifest(value) {
+    return (isRecord(value) &&
+        typeof value.model === 'string' &&
+        typeof value.dimensions === 'number' &&
+        typeof value.nextId === 'number' &&
+        typeof value.seq === 'number' &&
+        isRecord(value.artifacts));
+}
+function unit(vector) {
+    const norm = Math.hypot(...vector);
+    return norm > 0 ? vector.map((value) => value / norm) : vector;
+}
+function storageFor(dim) {
+    return dim % 8 === 0 && dim <= 1024 ? 'turbovec-q4' : 'f32';
+}
+function matches(embedding, want) {
+    return (embedding !== undefined &&
+        embedding.model === want.model &&
+        (want.dimensions === 0 || embedding.dimensions === want.dimensions) &&
+        embedding.vectors.length === want.chunks &&
+        embedding.vectors.every((row) => row.length === embedding.dimensions));
+}
+function isNotFound(error) {
+    return isRecord(error) && error.code === VECTOR_INDEX_NOT_FOUND;
+}
+export class KnowledgeStore {
+    _dir;
+    _model;
+    _maxChunks;
+    _minScore;
+    _embed;
+    _manifest;
+    _index;
+    _opened;
+    _lane;
+    constructor({ dir, model, maxChunks = Infinity, minScore = DEFAULT_MIN_SCORE, embed }) {
+        this._dir = dir;
+        this._model = model;
+        this._maxChunks = maxChunks;
+        this._minScore = minScore;
+        this._embed = embed;
+        this._manifest = emptyManifest(model);
+        this._index = null;
+        this._opened = null;
+        this._lane = Promise.resolve();
+    }
+    upsert(artifact) {
+        return this._serial(() => this._upsert(artifact));
+    }
+    remove(artifactId) {
+        return this._serial(async () => {
+            const removed = await this._drop(artifactId);
+            await this._persist();
+            return { removed };
+        });
+    }
+    search(query) {
+        return this._serial(() => this._search(query));
+    }
+    status() {
+        return this._serial(async () => {
+            const { model, dimensions, artifacts } = this._manifest;
+            const entries = Object.entries(artifacts).map(([artifactId, stored]) => ({
+                artifactId,
+                version: stored.version,
+                scope: stored.scope,
+                chunks: stored.chunks.length
+            }));
+            const chunks = entries.reduce((sum, entry) => sum + entry.chunks, 0);
+            return { model, dimensions, chunks, artifacts: entries };
+        });
+    }
+    async close() {
+        await this._lane.catch(noop);
+        await this._index?.dispose().catch(noop);
+        this._index = null;
+    }
+    _serial(run) {
+        const job = this._lane.then(async () => {
+            this._opened ??= this._open().catch((error) => {
+                this._opened = null;
+                throw error;
+            });
+            await this._opened;
+            return this._recovering(run);
+        });
+        this._lane = job.catch(noop);
+        return job;
+    }
+    async _recovering(run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (!isNotFound(error)) {
+                throw error;
+            }
+            this._index = null;
+            await this._open();
+            return run();
+        }
+    }
+    async _open() {
+        const saved = await readManifest(this._file(MANIFEST_FILE));
+        if (!saved || saved.model !== this._model) {
+            this._manifest = saved ?? emptyManifest(this._model);
+            await this._rebuild();
+            return;
+        }
+        this._manifest = saved;
+        const chunks = this._chunkCount();
+        if (chunks === 0) {
+            return;
+        }
+        try {
+            const { loadVectorIndex } = await this._embed.sdk();
+            const index = await loadVectorIndex({ path: this._file(INDEX_FILE) });
+            if (index.dim === saved.dimensions && index.length === chunks) {
+                this._index = index;
+                return;
+            }
+            await index.dispose();
+        }
+        catch {
+        }
+        await this._rebuild();
+    }
+    async _rebuild() {
+        const kept = Object.entries(this._manifest.artifacts).sort(([, a], [, b]) => a.seq - b.seq);
+        const stale = this._index;
+        this._manifest = { ...emptyManifest(this._model), seq: this._manifest.seq };
+        this._index = null;
+        try {
+            for (const [artifactId, stored] of kept) {
+                const chunks = stored.chunks.map(({ chunkId, text, metadata }) => ({
+                    id: chunkId,
+                    text,
+                    metadata
+                }));
+                const artifact = { artifactId, version: stored.version, scope: stored.scope, chunks };
+                await this._add(artifact, { heal: false });
+            }
+        }
+        catch (error) {
+            await this._unload();
+            throw error;
+        }
+        finally {
+            await stale?.dispose().catch(noop);
+        }
+        await this._persist();
+    }
+    async _unload() {
+        await this._index?.dispose().catch(noop);
+        this._index = null;
+        this._opened = null;
+    }
+    async _upsert(artifact) {
+        await this._drop(artifact.artifactId);
+        const result = await this._add(artifact);
+        await this._evict(artifact.artifactId);
+        await this._persist();
+        return result;
+    }
+    async _add(artifact, { heal = true } = {}) {
+        const { artifactId, version, scope, chunks, embedding } = artifact;
+        if (chunks.length === 0) {
+            return { added: 0, embedded: null };
+        }
+        const want = {
+            model: this._model,
+            dimensions: this._manifest.dimensions,
+            chunks: chunks.length
+        };
+        const embedded = matches(embedding, want) ? null : await this._embedChunks(artifact);
+        const vectors = embedded?.vectors ?? embedding?.vectors ?? [];
+        const dim = vectors[0]?.length ?? 0;
+        if (heal && this._index && this._index.dim !== dim) {
+            await this._rebuild();
+        }
+        const index = await this._indexFor(dim);
+        const manifest = this._manifest;
+        const stored = chunks.map((chunk) => ({
+            id: String(manifest.nextId++),
+            chunkId: chunk.id,
+            text: chunk.text,
+            metadata: chunk.metadata
+        }));
+        await index.add({ ids: stored.map((chunk) => chunk.id), vectors: vectors.map(unit) });
+        manifest.seq++;
+        manifest.artifacts[artifactId] = {
+            version,
+            scope,
+            seq: manifest.seq,
+            chunks: stored
+        };
+        return { added: stored.length, embedded };
+    }
+    async _embedChunks({ chunks }) {
+        const vectors = await this._embed.embed({
+            model: this._model,
+            texts: chunks.map((chunk) => chunk.text)
+        });
+        if (vectors.length !== chunks.length) {
+            throw new Error(`embed returned ${vectors.length} vectors for ${chunks.length} chunks`);
+        }
+        return { model: this._model, dimensions: vectors[0]?.length ?? 0, vectors };
+    }
+    async _indexFor(dim) {
+        if (this._index) {
+            if (this._index.dim !== dim) {
+                throw new Error(`the knowledge index holds ${this._index.dim} dimensions, not ${dim}`);
+            }
+            return this._index;
+        }
+        const { createVectorIndex } = await this._embed.sdk();
+        this._index = await createVectorIndex({ dim, storage: storageFor(dim) });
+        this._manifest.dimensions = dim;
+        return this._index;
+    }
+    async _drop(artifactId) {
+        const stored = this._manifest.artifacts[artifactId];
+        if (!stored) {
+            return 0;
+        }
+        if (this._index && stored.chunks.length) {
+            await this._index.remove({ ids: stored.chunks.map((chunk) => chunk.id) });
+        }
+        delete this._manifest.artifacts[artifactId];
+        return stored.chunks.length;
+    }
+    async _evict(keep) {
+        const oldest = Object.entries(this._manifest.artifacts)
+            .filter(([artifactId]) => artifactId !== keep)
+            .sort(([, a], [, b]) => a.seq - b.seq);
+        let total = this._chunkCount();
+        for (const [artifactId] of oldest) {
+            if (total <= this._maxChunks)
+                return;
+            total -= await this._drop(artifactId);
+        }
+    }
+    async _search({ text, scopes, k = DEFAULT_K, signal }) {
+        const granted = new Set(scopes);
+        const inScope = Object.values(this._manifest.artifacts)
+            .filter((stored) => granted.has(stored.scope))
+            .reduce((sum, stored) => sum + stored.chunks.length, 0);
+        if (!this._index || inScope === 0 || k <= 0) {
+            return [];
+        }
+        const [query = []] = await this._embed.embed({ model: this._model, texts: [text], signal });
+        if (query.length !== this._index.dim) {
+            await this._rebuild();
+        }
+        const index = this._index;
+        const byId = this._chunksById(granted);
+        const want = Math.min(k, inScope);
+        let fetch = Math.min(index.length, want * 4);
+        for (;;) {
+            const hits = await index.search({ query: unit(query), k: fetch });
+            const found = hits.flatMap((hit) => {
+                const entry = byId.get(hit.id);
+                return entry && hit.score >= this._minScore ? [{ ...entry, score: hit.score }] : [];
+            });
+            const floored = (hits.at(-1)?.score ?? -Infinity) < this._minScore;
+            if (found.length >= want || floored || fetch >= index.length) {
+                return found.slice(0, k);
+            }
+            fetch = Math.min(index.length, fetch * 4);
+        }
+    }
+    _chunksById(granted) {
+        const byId = new Map();
+        for (const [artifactId, stored] of Object.entries(this._manifest.artifacts)) {
+            if (!granted.has(stored.scope))
+                continue;
+            for (const chunk of stored.chunks) {
+                byId.set(chunk.id, {
+                    artifactId,
+                    chunkId: chunk.chunkId,
+                    scope: stored.scope,
+                    text: chunk.text,
+                    metadata: chunk.metadata
+                });
+            }
+        }
+        return byId;
+    }
+    _chunkCount() {
+        return Object.values(this._manifest.artifacts).reduce((sum, stored) => sum + stored.chunks.length, 0);
+    }
+    _file(name) {
+        return path.join(this._dir, name);
+    }
+    async _persist() {
+        await fs.promises.mkdir(this._dir, { recursive: true });
+        const snapshot = this._file(INDEX_FILE);
+        if (this._index && this._chunkCount() > 0) {
+            await this._index.write({ path: snapshot });
+        }
+        else {
+            await this._index?.dispose();
+            this._index = null;
+            this._manifest.dimensions = 0;
+            await fs.promises.rm(snapshot, { force: true });
+        }
+        const manifest = this._file(MANIFEST_FILE);
+        await fs.promises.writeFile(`${manifest}.tmp`, JSON.stringify(this._manifest));
+        await fs.promises.rename(`${manifest}.tmp`, manifest);
+    }
+}
+async function readManifest(file) {
+    try {
+        const value = JSON.parse(await fs.promises.readFile(file, 'utf8'));
+        return isManifest(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function noop() { }

package/dist-lib/plugins/lsp/index.d.ts

@@ -0,0 +1,32 @@
+import type { HarnessPlugin, PluginContext, PluginSetup } from '../../lib/plugins/index.ts';
+import type { LspServerConfig, SpawnServer } from './server.ts';
+export type { LspServerConfig, ServerProcess, SpawnOptions, SpawnServer } from './server.ts';
+export interface LspOptions {
+    readonly servers: readonly LspServerConfig[];
+    readonly idleMs?: number;
+    readonly requestTimeoutMs?: number;
+    readonly deniedRoots?: readonly string[];
+    readonly spawn?: SpawnServer;
+    readonly read?: readonly string[];
+}
+export declare class LspPlugin implements HarnessPlugin {
+    readonly name = "lsp";
+    readonly api = 1;
+    readonly addons: {
+        'bare-subprocess': () => Promise<{
+            constants: Record<string, number>;
+            errors: typeof import("bare-subprocess").errors;
+            Subprocess: typeof import("bare-subprocess").Subprocess;
+            spawn(file: string, args?: string[] | null, opts?: import("bare-subprocess").SpawnOptions): import("bare-subprocess").Subprocess;
+            spawn(file: string, opts?: import("bare-subprocess").SpawnOptions): import("bare-subprocess").Subprocess;
+            spawnSync(file: string, args?: string[] | null, opts?: import("bare-subprocess").SpawnSyncOptions): import("bare-subprocess").SpawnSyncResult;
+            spawnSync(file: string, opts?: import("bare-subprocess").SpawnSyncOptions): import("bare-subprocess").SpawnSyncResult;
+            default: typeof import("bare-subprocess");
+        }>;
+    };
+    readonly read: readonly string[] | undefined;
+    private readonly _options;
+    constructor(options: LspOptions);
+    validate(): string | null;
+    setup(ctx: PluginContext): PluginSetup;
+}

package/dist-lib/plugins/lsp/index.js

@@ -0,0 +1,77 @@
+import path from 'path';
+import { PluginRegistry } from '../../lib/plugins/index.js';
+import { ServerPool } from './pool.js';
+import { createLspTool } from './tool.js';
+const IDLE_MS = 5 * 60_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+const START_WAIT_MS = 30_000;
+function positive(value) {
+    return value === undefined || (Number.isFinite(value) && value > 0);
+}
+function serverError(server, languages, claimed) {
+    if (!server.language)
+        return 'each server needs a language';
+    const named = `server '${server.language}'`;
+    if (languages.has(server.language)) {
+        return `${named} is configured twice`;
+    }
+    languages.add(server.language);
+    if (!path.isAbsolute(server.command ?? '')) {
+        return `${named} needs an absolute command`;
+    }
+    if (!server.extensions?.length) {
+        return `${named} needs extensions`;
+    }
+    const taken = server.extensions.find((ext) => !ext.startsWith('.') || claimed.has(ext));
+    if (taken) {
+        return `${named} extension '${taken}' needs a dot and one server`;
+    }
+    for (const ext of server.extensions) {
+        claimed.add(ext);
+    }
+    return null;
+}
+export class LspPlugin {
+    name = 'lsp';
+    api = PluginRegistry.API_VERSION;
+    addons = { 'bare-subprocess': () => import('bare-subprocess') };
+    read;
+    _options;
+    constructor(options) {
+        this._options = options;
+        this.read = options?.read;
+    }
+    validate() {
+        const config = this._options;
+        if (!config?.servers?.length) {
+            return 'config needs at least one server';
+        }
+        if (!positive(config.idleMs) || !positive(config.requestTimeoutMs)) {
+            return 'idleMs and requestTimeoutMs must be positive';
+        }
+        const languages = new Set();
+        const claimed = new Set();
+        for (const server of config.servers) {
+            const error = serverError(server, languages, claimed);
+            if (error) {
+                return error;
+            }
+        }
+        return null;
+    }
+    setup(ctx) {
+        const config = this._options;
+        const pool = new ServerPool({
+            idleMs: config.idleMs ?? IDLE_MS,
+            startWaitMs: START_WAIT_MS,
+            spawn: config.spawn
+        });
+        const tool = createLspTool({
+            pool,
+            servers: config.servers,
+            requestTimeoutMs: config.requestTimeoutMs ?? REQUEST_TIMEOUT_MS,
+            deniedRoots: [...new Set([...ctx.deniedRoots, ...(config.deniedRoots ?? [])])]
+        });
+        return { tools: [tool], teardown: () => pool.close() };
+    }
+}