@qvac/core 0.0.0 → 0.1.1

package/dist-lib/lib/core/files/store/server.d.ts

@@ -0,0 +1,27 @@
+import type Corestore from 'corestore';
+import ReadyResource from 'ready-resource';
+import type { LinkableAttachment } from '../../attachment-link.ts';
+import type Hyperblobs from 'hyperblobs';
+export type CurrentMeshKeys = () => {
+    blobs: Hyperblobs;
+    encryptionKey: Buffer;
+} | null;
+export declare class CoreBlobServer extends ReadyResource {
+    private readonly _store;
+    private readonly _mesh;
+    private readonly _server;
+    private readonly _probes;
+    private readonly _readTimeoutMs;
+    private _suspended;
+    constructor(store: Corestore, mesh: CurrentMeshKeys, { readTimeoutMs }?: {
+        readTimeoutMs?: number | undefined;
+    });
+    get port(): number;
+    link({ blobId, mimeType }: LinkableAttachment): string | null;
+    suspend(): Promise<void>;
+    resume(): Promise<void>;
+    _open(): Promise<void>;
+    _close(): Promise<void>;
+    private _resolve;
+    private _parse;
+}

package/dist-lib/lib/core/files/store/server.js

@@ -0,0 +1,114 @@
+import BlobServer, {} from 'hypercore-blob-server';
+import ReadyResource from 'ready-resource';
+import { isInvalidBlobReferenceError, parseBlobReference } from "./reference.js";
+export class CoreBlobServer extends ReadyResource {
+    _store;
+    _mesh;
+    _server;
+    _probes = new Set();
+    _readTimeoutMs;
+    _suspended = false;
+    constructor(store, mesh, { readTimeoutMs = 15_000 } = {}) {
+        super();
+        this._store = store.session();
+        this._mesh = mesh;
+        this._readTimeoutMs = readTimeoutMs;
+        this._server = new BlobServer(this._store, {
+            resolve: (key, info) => this._resolve(key, info)
+        });
+    }
+    get port() {
+        return this._server.port;
+    }
+    link({ blobId, mimeType }) {
+        if (!this.opened || this.closing)
+            return null;
+        const current = this._mesh();
+        if (!current)
+            return null;
+        const parsed = this._parse(blobId);
+        if (!parsed || parsed.inline)
+            return null;
+        return this._server.getLink(parsed.coreKey ?? current.blobs.core.key.toString('hex'), {
+            blob: parsed.blobId,
+            type: mimeType || 'application/octet-stream'
+        });
+    }
+    async suspend() {
+        if (this.closing)
+            return;
+        this._suspended = true;
+        if (!this.opened)
+            await this.ready();
+        await Promise.all([...this._probes].map((core) => core.close()));
+        await this._server.suspend();
+    }
+    async resume() {
+        if (this.closing)
+            return;
+        if (!this.opened)
+            await this.ready();
+        if (this.closing)
+            return;
+        this._suspended = false;
+        const before = this._server.port;
+        await this._server.resume();
+        if (this._server.port !== before)
+            this.emit('rebound', this._server.port);
+    }
+    async _open() {
+        await this._server.listen();
+    }
+    async _close() {
+        await Promise.all([...this._probes].map((core) => core.close()));
+        await this._server.close();
+        await this._store.close();
+    }
+    async _resolve(key, info) {
+        const current = this._mesh();
+        if (!current || this.closing || this._suspended)
+            return null;
+        const keys = { encryptionKey: current.encryptionKey };
+        const { blob, range } = info;
+        if (!blob || info.head || blob.byteLength === 0)
+            return keys;
+        const start = range?.start ?? 0;
+        const end = !range || range.end === -1 ? blob.byteLength - 1 : Math.min(range.end, blob.byteLength - 1);
+        if (start > end)
+            return keys;
+        const core = this._store.get({ key, ...keys });
+        const deadline = Date.now() + this._readTimeoutMs;
+        this._probes.add(core);
+        try {
+            await core.ready();
+            if (this.closing || this._suspended || Date.now() >= deadline)
+                return null;
+            const position = start === 0
+                ? [blob.blockOffset, 0]
+                : await core.seek(blob.byteOffset + start, {
+                    timeout: Math.max(1, deadline - Date.now())
+                });
+            if (!position || this.closing || this._suspended || Date.now() >= deadline)
+                return null;
+            const bytes = await core.get(position[0], { timeout: Math.max(1, deadline - Date.now()) });
+            return bytes && this._mesh() === current && !this.closing && !this._suspended ? keys : null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            this._probes.delete(core);
+            await core.close();
+        }
+    }
+    _parse(blobReference) {
+        try {
+            return parseBlobReference(blobReference);
+        }
+        catch (err) {
+            if (isInvalidBlobReferenceError(err))
+                return null;
+            throw err;
+        }
+    }
+}

package/dist-lib/lib/core/files/store/sweep.d.ts

@@ -0,0 +1,2 @@
+import type Hyperblobs from 'hyperblobs';
+export declare function sweepUnreferenced(blobs: Hyperblobs, references: string[], coreLength: number): Promise<void>;

package/dist-lib/lib/core/files/store/sweep.js

@@ -0,0 +1,45 @@
+import { parseBlobReference, parseBlobReferenceCoreKey } from "./reference.js";
+export async function sweepUnreferenced(blobs, references, coreLength) {
+    const ranges = [];
+    const key = blobs.core.key.toString('hex');
+    for (const reference of references)
+        addLocalRange(ranges, reference, key, coreLength);
+    await clearGaps(blobs, mergeRanges(ranges), coreLength);
+}
+function addLocalRange(ranges, reference, localCoreKey, coreLength) {
+    const coreKey = parseBlobReferenceCoreKey(reference);
+    if (coreKey && coreKey !== localCoreKey)
+        return;
+    const { blobId } = parseBlobReference(reference);
+    const end = blobId.blockOffset + blobId.blockLength;
+    if (!Number.isSafeInteger(end) || end > coreLength) {
+        throw new TypeError('blob reference exceeds local core');
+    }
+    if (blobId.blockLength > 0)
+        ranges.push({ start: blobId.blockOffset, end });
+}
+function mergeRanges(ranges) {
+    const sorted = [...ranges].sort((a, b) => a.start - b.start || a.end - b.end);
+    const merged = [];
+    for (const range of sorted) {
+        const previous = merged.at(-1);
+        if (!previous || range.start > previous.end) {
+            merged.push(range);
+            continue;
+        }
+        if (range.end > previous.end) {
+            merged[merged.length - 1] = { start: previous.start, end: range.end };
+        }
+    }
+    return merged;
+}
+async function clearGaps(blobs, ranges, coreLength) {
+    let cursor = 0;
+    for (const range of ranges) {
+        if (cursor < range.start)
+            await blobs.core.clear(cursor, range.start);
+        cursor = range.end;
+    }
+    if (cursor < coreLength)
+        await blobs.core.clear(cursor, coreLength);
+}

package/dist-lib/lib/core/files/upload-input.d.ts

@@ -0,0 +1,27 @@
+import type { HandlerFrames } from '../../../spec/capabilities.d.ts';
+type UploadFrames<T> = HandlerFrames<T> & {
+    readonly writeStream?: {
+        readonly destroyed: boolean;
+        readonly destroying: boolean;
+        on(event: 'close', listener: () => void): void;
+        off(event: 'close', listener: () => void): void;
+    };
+};
+export declare class UploadInput<T extends {
+    data?: Buffer | null;
+}> {
+    readonly iterator: AsyncIterator<T>;
+    private readonly _abort;
+    private readonly _frames;
+    private readonly _source;
+    private readonly _onClose;
+    onData: ((bytes: number) => void) | null;
+    onFailure: ((error: unknown) => void) | null;
+    constructor(frames: AsyncIterable<T> | UploadFrames<T>, options: {
+        inactivityMs?: number;
+    });
+    check(): void;
+    fail(error: unknown): void;
+    close(): void;
+}
+export {};

package/dist-lib/lib/core/files/upload-input.js

@@ -0,0 +1,52 @@
+import { AbortController } from 'bare-abort-controller';
+import { toAsyncIterable } from "../async-iterable.js";
+import { nextFrame } from "../next-frame.js";
+import { AbortedError } from '@qvac/harness/race-abort';
+export class UploadInput {
+    iterator;
+    _abort = new AbortController();
+    _frames;
+    _source;
+    _onClose = () => {
+        const error = new AbortedError();
+        this._abort.abort(error);
+        this.fail(error);
+    };
+    onData = null;
+    onFailure = null;
+    constructor(frames, options) {
+        this._frames = frames;
+        const source = toAsyncIterable(frames)[Symbol.asyncIterator]();
+        this._source = source;
+        this.iterator = {
+            next: async () => {
+                this.check();
+                const frame = await nextFrame(source, { ...options, signal: this._abort.signal });
+                if (!frame.done && frame.value.data)
+                    this.onData?.(frame.value.data.length);
+                return frame;
+            }
+        };
+        if ('writeStream' in frames)
+            frames.writeStream?.on('close', this._onClose);
+    }
+    check() {
+        if (this._abort.signal.aborted)
+            throw new AbortedError();
+        if ('writeStream' in this._frames) {
+            const stream = this._frames.writeStream;
+            if (stream?.destroyed || stream?.destroying)
+                throw new AbortedError();
+        }
+    }
+    fail(error) {
+        this.onFailure?.(error);
+        this.onFailure = null;
+    }
+    close() {
+        this.fail(new AbortedError());
+        if ('writeStream' in this._frames)
+            this._frames.writeStream?.off('close', this._onClose);
+        void this._source.return?.().catch(() => { });
+    }
+}

package/dist-lib/lib/core/files/upload.d.ts

@@ -0,0 +1,32 @@
+import type { AssistantUploadAttachmentRequest } from '../../../spec/hyperschema/types.d.ts';
+import type { HandlerFrames } from '../../../spec/capabilities.d.ts';
+import type { Mesh } from '../mesh.ts';
+export declare function uploadFile(mesh: Mesh, frames: AsyncIterable<AssistantUploadAttachmentRequest> | HandlerFrames<AssistantUploadAttachmentRequest>, { kind, maxBytes, deviceId, inactivityMs }: {
+    kind: 'attachment' | 'knowledge';
+    maxBytes: number;
+    deviceId?: Buffer | null;
+    inactivityMs?: number;
+}): AsyncGenerator<{
+    bytesWritten: number;
+    attachment?: undefined;
+    knowledge?: undefined;
+} | {
+    bytesWritten: number;
+    attachment: {
+        id: string;
+        fileName: string;
+        mimeType: string;
+        byteLength: number;
+        blobId: string;
+        createdAt: number;
+    };
+    knowledge: import("../../../spec/index").QvacKnowledge | undefined;
+}, void, unknown>;
+export declare function capped(chunks: AsyncIterable<Buffer>, maxBytes: number, message: string): AsyncGenerator<Buffer>;
+export declare function dataFrames<T extends {
+    data?: Buffer | null;
+}>(rest: AsyncIterator<T>, firstData: Buffer | null | undefined): AsyncGenerator<Buffer>;
+export declare function peekHead(it: AsyncIterable<Buffer>, n: number): Promise<{
+    head: Buffer;
+    rest: AsyncIterable<Buffer>;
+}>;

package/dist-lib/lib/core/files/upload.js

@@ -0,0 +1,201 @@
+import b4a from 'b4a';
+import { isKnowledgeRoutedAttachment, routeAttachmentToKnowledge, removeKnowledge, syncAttachmentChunk } from "./records/index.js";
+import { normalizeImageForModel, IMAGE_MIMES } from "../image/normalize.js";
+import { detectImageMime, mapDeclaredToSniffed } from "../image/sniff.js";
+import { isSupportedRagDocument } from "./rag/index.js";
+import { appendChunk, updateChunk } from "../chunk.js";
+import { UploadInput } from "./upload-input.js";
+const MODEL_NATIVE_IMAGE_MIMES = new Set([
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'image/gif',
+    'image/bmp'
+]);
+const noop = () => { };
+export async function* uploadFile(mesh, frames, { kind, maxBytes, deviceId, inactivityMs }) {
+    const input = new UploadInput(frames, { inactivityMs });
+    const it = input.iterator;
+    let uploadId;
+    try {
+        const first = await it.next();
+        if (first.done)
+            return;
+        const { chatId, runId, fileName, mimeType, raw } = first.value;
+        const originDeviceId = kind === 'knowledge' ? deviceId : first.value.originDeviceId;
+        if (typeof chatId !== 'string' ||
+            typeof fileName !== 'string' ||
+            typeof mimeType !== 'string' ||
+            !originDeviceId) {
+            throw new Error(`upload${kind === 'knowledge' ? 'Knowledge' : 'Attachment'}: first frame must carry chatId, fileName, mimeType${kind === 'attachment' ? ', originDeviceId' : ''}`);
+        }
+        const upload = await mesh.files.beginUpload(first.value);
+        uploadId = upload.id;
+        input.onData = (bytes) => mesh.files.uploadProgress(upload.id, bytes);
+        input.onFailure = (error) => mesh.files.uploadFailed(upload.id, error);
+        const source = capped(dataFrames(it, first.value.data), maxBytes, `${kind} too large ${kind === 'attachment' ? '—' : '-'} the limit is ${maxBytes} bytes`);
+        let stream = source;
+        let storedMime = mimeType;
+        const declaredSniffed = mapDeclaredToSniffed(storedMime);
+        if (kind === 'knowledge') {
+            const { head, rest } = await peekHead(source, 4096);
+            if (declaredSniffed !== null && detectImageMime(head) !== declaredSniffed) {
+                throw new Error(`uploadKnowledge: bytes do not match declared mime ${mimeType}`);
+            }
+            if (!isSupportedRagDocument({ fileName, mimeType, bytes: head })) {
+                throw new Error(`${fileName} is not a supported Knowledge file.`);
+            }
+            stream = rest;
+        }
+        else if (declaredSniffed !== null) {
+            const { head, rest } = await peekHead(source, 12);
+            const sniffed = detectImageMime(head);
+            if (raw) {
+                if (sniffed !== declaredSniffed) {
+                    throw new Error(`uploadAttachment: bytes do not match declared mime ${storedMime}`);
+                }
+                stream = rest;
+            }
+            else if (sniffed === null) {
+                throw new Error(`uploadAttachment: bytes are not a valid image for ${storedMime}`);
+            }
+            else {
+                const pieces = [];
+                let received = 0;
+                const chunks = rest[Symbol.asyncIterator]();
+                let next = await chunks.next();
+                while (!next.done) {
+                    pieces.push(next.value);
+                    received += next.value.length;
+                    next = await chunks.next();
+                    if (!next.done)
+                        yield { bytesWritten: received };
+                }
+                const original = b4a.concat(pieces);
+                const bytes = await normalizeImageForModel(original);
+                if (bytes !== original) {
+                    storedMime = 'image/jpeg';
+                }
+                else if (MODEL_NATIVE_IMAGE_MIMES.has(sniffed)) {
+                    storedMime = sniffed;
+                }
+                else {
+                    throw new Error(`uploadAttachment: could not decode ${sniffed} image (it may be corrupt)`);
+                }
+                stream = (async function* () {
+                    yield bytes;
+                })();
+            }
+        }
+        let written;
+        for await (const frame of mesh.files.write(stream, { inactivityMs })) {
+            written = frame;
+            if (!('blobId' in frame))
+                yield { bytesWritten: frame.bytesWritten };
+        }
+        const final = written;
+        const attachment = {
+            id: upload.id,
+            fileName,
+            mimeType: storedMime,
+            byteLength: final.byteLength,
+            blobId: mesh.files.reference(final.blobId),
+            createdAt: Date.now()
+        };
+        let chunkId;
+        try {
+            input.check();
+            const preview = IMAGE_MIMES.has(storedMime.toLowerCase());
+            const appended = await appendChunk(mesh, {
+                id: preview ? upload.id : undefined,
+                display: preview ? { preview: true } : undefined,
+                chatId,
+                runId,
+                type: 'attachment',
+                attachment,
+                originDeviceId
+            });
+            chunkId = appended.id;
+        }
+        catch (err) {
+            await mesh.files.clear(attachment.blobId, attachment.id).catch(noop);
+            throw err;
+        }
+        let knowledge;
+        try {
+            input.check();
+            if (kind === 'knowledge' || (!runId && isKnowledgeRoutedAttachment(attachment))) {
+                knowledge = await routeAttachmentToKnowledge(mesh, chatId, attachment);
+            }
+            input.check();
+        }
+        catch (error) {
+            await removeKnowledge(mesh, { knowledgeId: upload.id, at: Date.now() }).catch(noop);
+            const tombstone = await updateChunk(mesh, {
+                id: chunkId,
+                attachment: { ...attachment, deletedAt: Date.now() }
+            }).catch(noop);
+            if (tombstone)
+                await syncAttachmentChunk(mesh, tombstone).catch(noop);
+            throw error;
+        }
+        mesh.files.uploadComplete(upload.id);
+        input.onFailure = null;
+        yield {
+            bytesWritten: written.bytesWritten,
+            attachment,
+            knowledge
+        };
+    }
+    catch (error) {
+        input.fail(error);
+        throw error;
+    }
+    finally {
+        input.close();
+        if (uploadId)
+            mesh.files.uploadClosed(uploadId);
+    }
+}
+export async function* capped(chunks, maxBytes, message) {
+    let total = 0;
+    for await (const chunk of chunks) {
+        total += chunk.length;
+        if (total > maxBytes)
+            throw new Error(message);
+        yield chunk;
+    }
+}
+export async function* dataFrames(rest, firstData) {
+    if (firstData)
+        yield firstData;
+    let next = await rest.next();
+    while (!next.done) {
+        if (next.value.data)
+            yield next.value.data;
+        next = await rest.next();
+    }
+}
+export async function peekHead(it, n) {
+    const iterator = it[Symbol.asyncIterator]();
+    const pieces = [];
+    let collected = 0;
+    while (collected < n) {
+        const next = await iterator.next();
+        if (next.done)
+            break;
+        pieces.push(next.value);
+        collected += next.value.length;
+    }
+    const head = Buffer.concat(pieces).subarray(0, Math.min(collected, n));
+    const rest = (async function* () {
+        for (const piece of pieces)
+            yield piece;
+        let step = await iterator.next();
+        while (!step.done) {
+            yield step.value;
+            step = await iterator.next();
+        }
+    })();
+    return { head, rest };
+}

package/dist-lib/lib/core/fs-drives.d.ts

@@ -0,0 +1,18 @@
+import Hyperdrive from 'hyperdrive';
+import type Corestore from 'corestore';
+import type Hyperswarm from 'hyperswarm';
+import type { BlindPeeringOpts } from './blind-peers.ts';
+export interface AcquiredDrive {
+    readonly drive: Hyperdrive;
+    readonly writable: boolean;
+}
+export interface DriveHost {
+    acquire(key: string): Promise<AcquiredDrive>;
+    close(): Promise<void>;
+}
+export interface DriveHostOptions {
+    readonly swarm: Hyperswarm;
+    readonly blindPeerKeys: ReadonlyArray<Buffer>;
+    readonly blindPeeringOpts?: BlindPeeringOpts;
+}
+export declare function createFsDriveHost(store: Corestore, opts: DriveHostOptions): DriveHost;

package/dist-lib/lib/core/fs-drives.js

@@ -0,0 +1,58 @@
+import BlindPeering from 'blind-peering';
+import Hyperdrive from 'hyperdrive';
+import HypercoreId from 'hypercore-id-encoding';
+const NAMESPACE = 'fs-drives';
+const DRIVE_OPEN_TIMEOUT_MS = 15_000;
+function withDeadline(promise, ms) {
+    const { promise: gated, resolve, reject } = Promise.withResolvers();
+    const timer = setTimeout(() => reject(new Error('drive open timed out on the host')), ms);
+    promise.then((value) => {
+        clearTimeout(timer);
+        resolve(value);
+    }, (err) => {
+        clearTimeout(timer);
+        reject(err);
+    });
+    return gated;
+}
+async function openDrive(store, swarm, key) {
+    const drive = new Hyperdrive(store, HypercoreId.decode(key));
+    await drive.ready();
+    const topic = swarm.join(drive.discoveryKey, { server: false, client: true });
+    const donePeering = drive.findingPeers();
+    topic.flushed().then(donePeering, donePeering);
+    return drive;
+}
+export function createFsDriveHost(store, opts) {
+    const namespaced = store.namespace(NAMESPACE);
+    const peering = new BlindPeering(opts.swarm.dht, namespaced, {
+        pick: 2,
+        ...opts.blindPeeringOpts
+    });
+    const drives = new Map();
+    async function acquire(key) {
+        const cached = drives.get(key);
+        if (cached)
+            return cached;
+        const opening = withDeadline((async () => {
+            const drive = await openDrive(namespaced, opts.swarm, key);
+            const blobs = await drive.getBlobs();
+            peering.addCoreBackground(drive.core, { keys: opts.blindPeerKeys });
+            if (blobs)
+                peering.addCoreBackground(blobs.core, { keys: opts.blindPeerKeys });
+            return { drive, writable: drive.writable };
+        })(), DRIVE_OPEN_TIMEOUT_MS);
+        drives.set(key, opening);
+        opening.catch(() => drives.delete(key));
+        return opening;
+    }
+    async function close() {
+        const settled = await Promise.allSettled(drives.values());
+        drives.clear();
+        await Promise.all(settled
+            .filter((result) => result.status === 'fulfilled')
+            .map((result) => result.value.drive.close()));
+        await peering.close();
+    }
+    return { acquire, close };
+}

package/dist-lib/lib/core/gpu-info-node.d.ts

@@ -0,0 +1,3 @@
+import type GPUInfo from 'bare-gpu-info';
+declare const ctor: (new () => GPUInfo) | null;
+export default ctor;

package/dist-lib/lib/core/gpu-info-node.js

@@ -0,0 +1,2 @@
+const ctor = null;
+export default ctor;

package/dist-lib/lib/core/handoff-channel.d.ts

@@ -0,0 +1,46 @@
+import type { Codec } from 'compact-encoding';
+export declare const HOST_UNREACHABLE = "the device hosting this agent is not connected";
+export declare const HOST_SILENT = "the device hosting this agent did not answer";
+export declare const ACK_TIMEOUT_MS = 60000;
+export interface HandoffStream {
+    readonly remotePublicKey: Uint8Array;
+    readonly noiseStream: {
+        userData: unknown;
+    };
+}
+export interface HandoffChannelOptions<Req, Res, Ack extends {
+    id: number;
+}> {
+    readonly protocol: string;
+    readonly requestEncoding: Codec<RequestMessage<Req>>;
+    readonly ackEncoding: Codec<Ack>;
+    readonly onrequest: (request: Req, from: Uint8Array) => Promise<Res>;
+    readonly buildAck: (id: number, error: string, result: Res | null) => Ack;
+    readonly readAck: (ack: Ack) => {
+        readonly error: string;
+        readonly result: Res;
+    };
+    readonly ackTimeoutMs?: number;
+}
+interface RequestMessage<Req> {
+    readonly id: number;
+    readonly request: Req;
+}
+export declare class HandoffChannel<Req, Res, Ack extends {
+    id: number;
+}> {
+    private readonly _opts;
+    private readonly _ackTimeoutMs;
+    private readonly _peers;
+    private readonly _waiters;
+    private _nextId;
+    constructor(opts: HandoffChannelOptions<Req, Res, Ack>);
+    addStream(stream: HandoffStream): void;
+    send(hostDeviceId: Uint8Array, request: Req): Promise<Res>;
+    destroy(): void;
+    private _serve;
+    private _settle;
+    private _drop;
+    private _fail;
+}
+export {};