@qvac/core 0.0.0 → 0.1.0

package/dist-lib/lib/core/handoff-channel.js

@@ -0,0 +1,102 @@
+import b4a from 'b4a';
+import Protomux, {} from 'protomux';
+export const HOST_UNREACHABLE = 'the device hosting this agent is not connected';
+export const HOST_SILENT = 'the device hosting this agent did not answer';
+export const ACK_TIMEOUT_MS = 60_000;
+export class HandoffChannel {
+    _opts;
+    _ackTimeoutMs;
+    _peers;
+    _waiters;
+    _nextId;
+    constructor(opts) {
+        this._opts = opts;
+        this._ackTimeoutMs = opts.ackTimeoutMs ?? ACK_TIMEOUT_MS;
+        this._peers = new Map();
+        this._waiters = new Map();
+        this._nextId = 0;
+    }
+    addStream(stream) {
+        const deviceId = b4a.toString(stream.remotePublicKey, 'hex');
+        if (this._peers.has(deviceId))
+            return;
+        const channel = Protomux.from(stream.noiseStream).createChannel({
+            protocol: this._opts.protocol,
+            onclose: () => {
+                if (channel)
+                    this._drop(deviceId, channel);
+            }
+        });
+        if (!channel)
+            return;
+        const requests = channel.addMessage({
+            encoding: this._opts.requestEncoding,
+            onmessage: (m) => void this._serve(deviceId, m)
+        });
+        const responses = channel.addMessage({
+            encoding: this._opts.ackEncoding,
+            onmessage: (m) => this._settle(deviceId, m)
+        });
+        this._peers.set(deviceId, { channel, remoteKey: stream.remotePublicKey, requests, responses });
+        channel.open();
+    }
+    send(hostDeviceId, request) {
+        const deviceId = b4a.toString(hostDeviceId, 'hex');
+        const peer = this._peers.get(deviceId);
+        if (!peer)
+            return Promise.reject(new Error(HOST_UNREACHABLE));
+        const id = this._nextId++;
+        const { promise, resolve, reject } = Promise.withResolvers();
+        const timer = setTimeout(() => this._fail((w) => w === this._waiters.get(id), new Error(HOST_SILENT)), this._ackTimeoutMs);
+        this._waiters.set(id, { deviceId, timer, resolve, reject });
+        peer.requests.send({ id, request });
+        return promise;
+    }
+    destroy() {
+        for (const peer of this._peers.values())
+            peer.channel.close();
+        this._peers.clear();
+        this._fail(() => true, new Error(`${this._opts.protocol} destroyed`));
+    }
+    async _serve(deviceId, m) {
+        const peer = this._peers.get(deviceId);
+        if (!peer)
+            return;
+        let error = '';
+        let result = null;
+        try {
+            result = await this._opts.onrequest(m.request, peer.remoteKey);
+        }
+        catch (err) {
+            error = err instanceof Error ? err.message : String(err);
+        }
+        peer.responses.send(this._opts.buildAck(m.id, error, result));
+    }
+    _settle(deviceId, ack) {
+        const waiter = this._waiters.get(ack.id);
+        if (!waiter || waiter.deviceId !== deviceId)
+            return;
+        this._waiters.delete(ack.id);
+        clearTimeout(waiter.timer);
+        const { error, result } = this._opts.readAck(ack);
+        if (error)
+            waiter.reject(new Error(error));
+        else
+            waiter.resolve(result);
+    }
+    _drop(deviceId, channel) {
+        if (this._peers.get(deviceId)?.channel !== channel)
+            return;
+        this._peers.delete(deviceId);
+        this._fail((waiter) => waiter.deviceId === deviceId, new Error(HOST_UNREACHABLE));
+    }
+    _fail(match, err) {
+        for (const [id, waiter] of this._waiters) {
+            if (!match(waiter))
+                continue;
+            this._waiters.delete(id);
+            clearTimeout(waiter.timer);
+            waiter.reject(err);
+        }
+    }
+}

package/dist-lib/lib/core/health-assistant.d.ts

@@ -0,0 +1,7 @@
+import type { QvacAgent, QvacDevice } from '../../spec/mesh/hyperschema/types.d.ts';
+export declare const HEALTH_ASSISTANT_ID = "qvac-health-assistant";
+export type HealthAssistantHost = Pick<QvacDevice, 'id' | 'platform'>;
+export interface HealthAssistantOptions {
+    readonly at?: number;
+}
+export declare function buildHealthAssistant(device: HealthAssistantHost, { at }?: HealthAssistantOptions): QvacAgent;

package/dist-lib/lib/core/health-assistant.js

@@ -0,0 +1,24 @@
+import { MEDPSY_1_7B, MEDPSY_4B } from '@qvac/harness/model-catalog';
+export const HEALTH_ASSISTANT_ID = 'qvac-health-assistant';
+export function buildHealthAssistant(device, { at = Date.now() } = {}) {
+    const mobile = device.platform === 'android' || device.platform === 'ios';
+    return {
+        id: HEALTH_ASSISTANT_ID,
+        name: 'Health Assistant',
+        bio: 'You are a health-focused assistant. Provide clear, helpful information about health and wellbeing.',
+        providerDeviceId: device.id,
+        modelName: mobile ? MEDPSY_1_7B : MEDPSY_4B,
+        reasoning: 'inherit',
+        enabledSkills: [],
+        enabledTools: [],
+        installedSkills: [],
+        isDefault: false,
+        iconName: 'heart',
+        toolsScope: 'all',
+        skillsScope: 'selected',
+        approvalMode: 'ask',
+        disabledToolsets: [],
+        createdAt: at,
+        updatedAt: at
+    };
+}

package/dist-lib/lib/core/helpers/index.d.ts

@@ -0,0 +1,5 @@
+import type { QvacDevice, QvacSeedDefaultsOperation } from '../../../spec/mesh/hyperschema/types.d.ts';
+import type { Mesh } from '../mesh.ts';
+export declare function buildDefaultSeed(device: QvacDevice, blindPeerKeys: ReadonlyArray<Buffer>): QvacSeedDefaultsOperation;
+export declare function isOwnRevokedRow(mesh: Mesh, device: QvacDevice): boolean;
+export declare function isOwnKickedRow(mesh: Mesh, device: QvacDevice): boolean;

package/dist-lib/lib/core/helpers/index.js

@@ -0,0 +1,74 @@
+import { randomId } from "../id.js";
+const DEFAULT_AGENT_NAME = 'QV.AC';
+const DEFAULT_AGENT_BIO = 'You are a helpful local assistant. Be clear, practical, and concise.';
+const DEFAULT_AGENT_ICON = 'artificial-intelligence';
+const DEFAULT_FIRST_CHAT_TITLE = 'New Chat';
+function seedableAgent(agent) {
+    return {
+        id: agent.id,
+        name: agent.name,
+        bio: agent.bio,
+        providerDeviceId: agent.providerDeviceId,
+        modelName: agent.modelName,
+        reasoning: agent.reasoning,
+        enabledSkills: agent.enabledSkills,
+        enabledTools: agent.enabledTools,
+        installedSkills: agent.installedSkills,
+        isDefault: agent.isDefault,
+        iconName: agent.iconName,
+        toolsScope: agent.toolsScope,
+        skillsScope: agent.skillsScope,
+        createdAt: agent.createdAt,
+        updatedAt: agent.updatedAt
+    };
+}
+function seedableChat(chat) {
+    return {
+        id: chat.id,
+        agentId: chat.agentId,
+        title: chat.title,
+        webSearchEnabled: chat.webSearchEnabled,
+        createdAt: chat.createdAt,
+        updatedAt: chat.updatedAt
+    };
+}
+export function buildDefaultSeed(device, blindPeerKeys) {
+    const now = Date.now();
+    const agentId = randomId();
+    return {
+        agent: seedableAgent({
+            id: agentId,
+            name: DEFAULT_AGENT_NAME,
+            bio: DEFAULT_AGENT_BIO,
+            providerDeviceId: device.id,
+            modelName: device.recommendedModelName,
+            reasoning: 'inherit',
+            enabledSkills: [],
+            enabledTools: [],
+            installedSkills: [],
+            isDefault: true,
+            iconName: DEFAULT_AGENT_ICON,
+            toolsScope: 'all',
+            skillsScope: 'selected',
+            createdAt: now,
+            updatedAt: now
+        }),
+        chat: seedableChat({
+            id: randomId(),
+            agentId,
+            title: DEFAULT_FIRST_CHAT_TITLE,
+            webSearchEnabled: true,
+            createdAt: now,
+            updatedAt: now
+        }),
+        blindPeers: blindPeerKeys.map((key) => ({ key }))
+    };
+}
+export function isOwnRevokedRow(mesh, device) {
+    return device.revoked === true && device.writerKey?.equals(mesh.localWriterKey) === true;
+}
+export function isOwnKickedRow(mesh, device) {
+    if (!isOwnRevokedRow(mesh, device))
+        return false;
+    return device.revokedBy?.equals(mesh.localWriterKey) !== true;
+}

package/dist-lib/lib/core/hosted-agents.d.ts

@@ -0,0 +1,36 @@
+import type { Logger } from '../logger-type.ts';
+import type { AssistantSkill } from '../../spec/hyperschema/types.d.ts';
+import type { openLocalStore } from './local/index.ts';
+import type { Mesh } from './mesh.ts';
+import type { SecretRequest } from './secret-handoff.ts';
+export declare const HELD_AGENTS_KEY = "skill-values.held-agents";
+export interface HostedAgentsOptions {
+    readonly mesh: Mesh;
+    readonly local: ReturnType<typeof openLocalStore>;
+    readonly deviceId: Buffer;
+    readonly catalog: () => Promise<ReadonlyArray<AssistantSkill>>;
+    readonly send: (hostDeviceId: Uint8Array, request: SecretRequest) => Promise<void>;
+    readonly onmoved: () => Promise<unknown>;
+    readonly log?: Logger | null;
+}
+export declare class HostedAgents {
+    private readonly _mesh;
+    private readonly _local;
+    private readonly _deviceId;
+    private readonly _catalog;
+    private readonly _send;
+    private readonly _onmoved;
+    private readonly _log;
+    private readonly _lock;
+    private _closed;
+    private readonly _onDirty;
+    constructor(opts: HostedAgentsOptions);
+    start(): void;
+    kick(): void;
+    close(): Promise<void>;
+    private _run;
+    private _pass;
+    private _handOver;
+    private _stored;
+    private _held;
+}

package/dist-lib/lib/core/hosted-agents.js

@@ -0,0 +1,127 @@
+import b4a from 'b4a';
+import ScopeLock from 'scope-lock';
+import { getAgent, listAgents } from "./agent.js";
+import { agentSkillValues } from "./skill-secrets.js";
+const SCOPE = ['p2p', 'skill-values'];
+export const HELD_AGENTS_KEY = 'skill-values.held-agents';
+export class HostedAgents {
+    _mesh;
+    _local;
+    _deviceId;
+    _catalog;
+    _send;
+    _onmoved;
+    _log;
+    _lock = new ScopeLock({ debounce: true });
+    _closed;
+    _onDirty = () => this.kick();
+    constructor(opts) {
+        this._mesh = opts.mesh;
+        this._local = opts.local;
+        this._deviceId = opts.deviceId;
+        this._catalog = opts.catalog;
+        this._send = opts.send;
+        this._onmoved = opts.onmoved;
+        this._log = opts.log ?? null;
+        this._closed = false;
+    }
+    start() {
+        this._mesh.on('agents-dirty', this._onDirty);
+        this.kick();
+    }
+    kick() {
+        void this._run();
+    }
+    async close() {
+        this._closed = true;
+        this._mesh.off('agents-dirty', this._onDirty);
+        this._lock.destroy();
+        await this._lock.flush();
+    }
+    async _run() {
+        if (this._closed)
+            return;
+        if (!(await this._lock.lock()))
+            return;
+        try {
+            if (!this._closed && !this._mesh.closing)
+                await this._pass();
+        }
+        catch (err) {
+            this._log?.warn(SCOPE, 'hosted agent pass failed', err);
+        }
+        finally {
+            this._lock.unlock();
+        }
+    }
+    async _pass() {
+        const held = await this._held();
+        const hosted = new Set((await listAgents(this._mesh))
+            .filter((agent) => b4a.equals(agent.providerDeviceId, this._deviceId))
+            .map((agent) => agent.id));
+        const holding = new Set([...held, ...hosted]);
+        const departed = [...holding].filter((id) => !hosted.has(id));
+        if (departed.length > 0) {
+            const catalog = await this._catalog();
+            for (const id of departed) {
+                try {
+                    if (await this._handOver(id, catalog))
+                        holding.delete(id);
+                }
+                catch (err) {
+                    this._log?.warn(SCOPE, 'skill values could not follow the agent', err);
+                }
+            }
+        }
+        if (!sameIds(held, holding))
+            await this._local.set(HELD_AGENTS_KEY, [...holding]);
+    }
+    async _handOver(id, catalog) {
+        const agent = await getAgent(this._mesh, id);
+        if (!agent)
+            return false;
+        if (agent.deletedAt)
+            return true;
+        const stored = await this._stored(agentSkillValues(catalog, agent));
+        if (stored.length === 0)
+            return true;
+        for (const [skillName, values] of bySkill(stored)) {
+            await this._send(agent.providerDeviceId, { agentId: id, skillName, values });
+        }
+        await this._local.deleteAll(stored.map((value) => value.storageKey));
+        await this._onmoved();
+        return true;
+    }
+    async _stored(values) {
+        const stored = [];
+        for (const value of values) {
+            const held = await this._local.get(value.storageKey);
+            if (typeof held === 'string' && held !== '')
+                stored.push({ ...value, value: held });
+        }
+        return stored;
+    }
+    async _held() {
+        const stored = await this._local.get(HELD_AGENTS_KEY);
+        const ids = new Set();
+        if (Array.isArray(stored)) {
+            for (const id of stored) {
+                if (typeof id === 'string')
+                    ids.add(id);
+            }
+        }
+        return ids;
+    }
+}
+function sameIds(a, b) {
+    return a.size === b.size && [...a].every((id) => b.has(id));
+}
+function bySkill(values) {
+    const bundles = new Map();
+    for (const { skillName, key, value } of values) {
+        const bundle = bundles.get(skillName) ?? [];
+        bundle.push({ key, value });
+        bundles.set(skillName, bundle);
+    }
+    return bundles;
+}

package/dist-lib/lib/core/id.d.ts

@@ -0,0 +1 @@
+export declare function randomId(): string;

package/dist-lib/lib/core/id.js

@@ -0,0 +1,5 @@
+import b4a from 'b4a';
+import crypto from 'hypercore-crypto';
+export function randomId() {
+    return b4a.toString(crypto.randomBytes(16), 'hex');
+}

package/dist-lib/lib/core/identity.d.ts

@@ -0,0 +1,14 @@
+import type { KeyPair } from 'hypercore-crypto';
+export declare const MAX_PROOF_BYTES = 1024;
+export interface MintedIdentity {
+    readonly publicKey: Buffer;
+    readonly proof: Buffer;
+}
+export interface ExpectedDeviceProof {
+    readonly memberId: Buffer;
+    readonly deviceId: Buffer;
+}
+export declare function generateMnemonic(): Promise<string>;
+export declare function mintIdentity(mnemonic: string, devicePublicKey: Buffer): Promise<MintedIdentity>;
+export declare function attestDeviceProof(devicePublicKey: Buffer, parent: KeyPair, parentProof: Buffer): Promise<Buffer>;
+export declare function verifyDeviceProof(proof: Buffer, expected: ExpectedDeviceProof): Promise<boolean>;

package/dist-lib/lib/core/identity.js

@@ -0,0 +1,45 @@
+import c from 'compact-encoding';
+import { ProofEncoding } from 'keet-identity-key/lib/encoding.js';
+export const MAX_PROOF_BYTES = 1024;
+let loaded = null;
+async function identityKey() {
+    if (loaded === null)
+        loaded = await import('keet-identity-key');
+    return loaded.default;
+}
+export async function generateMnemonic() {
+    return (await identityKey()).generateMnemonic();
+}
+export async function mintIdentity(mnemonic, devicePublicKey) {
+    const IdentityKey = await identityKey();
+    const identity = await IdentityKey.from({ mnemonic });
+    return { publicKey: identity.identityPublicKey, proof: await identity.bootstrap(devicePublicKey) };
+}
+export async function attestDeviceProof(devicePublicKey, parent, parentProof) {
+    if (!parentProof)
+        throw new Error('attestDeviceProof needs the parent proof');
+    return (await identityKey()).attestDevice(devicePublicKey, parent, parentProof);
+}
+export async function verifyDeviceProof(proof, expected) {
+    if (proof.byteLength > MAX_PROOF_BYTES)
+        return false;
+    let decoded;
+    try {
+        decoded = c.decode(ProofEncoding, proof);
+    }
+    catch {
+        return false;
+    }
+    if (decoded.data)
+        return false;
+    try {
+        const IdentityKey = await identityKey();
+        return !!IdentityKey.verify(proof, null, {
+            expectedIdentity: expected.memberId,
+            expectedDevice: expected.deviceId
+        });
+    }
+    catch {
+        return false;
+    }
+}

package/dist-lib/lib/core/image/cache-sweep.d.ts

@@ -0,0 +1,12 @@
+export declare const IMAGE_CACHE_MAX_BYTES: number;
+export declare const IMAGE_CACHE_MAX_AGE_MS: number;
+export declare function imageCacheName(image: {
+    blobId: string;
+    fileName: string;
+}): string;
+export declare function sweepImageCache(dir: string, { maxBytes, maxAgeMs, keep, inUse }?: {
+    maxBytes?: number;
+    maxAgeMs?: number;
+    keep?: ReadonlySet<string>;
+    inUse?: (name: string) => boolean;
+}): Promise<void>;

package/dist-lib/lib/core/image/cache-sweep.js

@@ -0,0 +1,67 @@
+import fs from 'fs';
+import crypto from 'hypercore-crypto';
+import path from 'path';
+export const IMAGE_CACHE_MAX_BYTES = 512 * 1024 * 1024;
+export const IMAGE_CACHE_MAX_AGE_MS = 365 * 24 * 60 * 60 * 1000;
+const STALE_PARTIAL_MS = 60 * 60 * 1000;
+const STAGING_SUFFIX = /\.partial-[0-9a-f]{8}$/;
+export function imageCacheName(image) {
+    const key = crypto.hash(Buffer.from(image.blobId)).toString('hex').slice(0, 32);
+    const name = image.fileName.replace(/[^a-zA-Z0-9_.-]/g, '_').slice(-40);
+    return `${key}-${name}`;
+}
+export async function sweepImageCache(dir, { maxBytes = IMAGE_CACHE_MAX_BYTES, maxAgeMs = IMAGE_CACHE_MAX_AGE_MS, keep, inUse } = {}) {
+    const names = await fs.promises.readdir(dir).catch(toNull);
+    if (!names)
+        return;
+    const now = Date.now();
+    const entries = [];
+    let total = 0;
+    for (const entry of await liveEntries(dir, names, now)) {
+        total += entry.size;
+        if (inUse?.(entry.name))
+            continue;
+        if (keep && !keep.has(entry.name)) {
+            await fs.promises.unlink(entry.file).catch(noop);
+            total -= entry.size;
+            continue;
+        }
+        if (now - entry.mtimeMs > maxAgeMs) {
+            await fs.promises.unlink(entry.file).catch(noop);
+            total -= entry.size;
+            continue;
+        }
+        entries.push(entry);
+    }
+    if (total <= maxBytes)
+        return;
+    entries.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    for (const entry of entries) {
+        if (total <= maxBytes)
+            return;
+        if (inUse?.(entry.name))
+            continue;
+        await fs.promises.unlink(entry.file).catch(noop);
+        total -= entry.size;
+    }
+}
+async function liveEntries(dir, names, now) {
+    const entries = [];
+    for (const name of names) {
+        const file = path.join(dir, name);
+        const stats = await fs.promises.stat(file).catch(toNull);
+        if (!stats?.isFile())
+            continue;
+        if (STAGING_SUFFIX.test(name)) {
+            if (now - stats.mtimeMs > STALE_PARTIAL_MS)
+                await fs.promises.unlink(file).catch(noop);
+            continue;
+        }
+        entries.push({ file, name, size: stats.size, mtimeMs: stats.mtimeMs });
+    }
+    return entries;
+}
+function toNull() {
+    return null;
+}
+function noop() { }

package/dist-lib/lib/core/image/normalize.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_IMAGE_WIDTH = 768;
+export declare const IMAGE_MIMES: Set<string>;
+export declare function normalizeImageForModel(bytes: Uint8Array): Promise<Uint8Array>;

package/dist-lib/lib/core/image/normalize.js

@@ -0,0 +1,49 @@
+export const MAX_IMAGE_WIDTH = 768;
+export const IMAGE_MIMES = new Set([
+    'image/jpeg',
+    'image/jpg',
+    'image/png',
+    'image/webp',
+    'image/gif',
+    'image/bmp',
+    'image/x-ms-bmp',
+    'image/heic',
+    'image/heif',
+    'image/avif',
+    'image/tiff',
+    'image/tif'
+]);
+let media;
+async function loadMedia() {
+    if (media !== undefined)
+        return media;
+    try {
+        media = await import('bare-media');
+    }
+    catch {
+        media = null;
+    }
+    return media;
+}
+export async function normalizeImageForModel(bytes) {
+    const mod = await loadMedia();
+    if (!mod)
+        return bytes;
+    try {
+        const frame = firstFrame(await mod.image.decode(bytes));
+        const oriented = await mod.image.orientate(frame, { file: bytes });
+        const resized = await mod.image.resize(oriented, { maxWidth: MAX_IMAGE_WIDTH });
+        return await mod.image.encode(resized, { mimetype: 'image/jpeg' });
+    }
+    catch {
+        return bytes;
+    }
+}
+function firstFrame(decoded) {
+    if (!decoded.frames)
+        return decoded;
+    const [first] = decoded.frames;
+    if (!first)
+        throw new Error('decoded image had no frames');
+    return first;
+}

package/dist-lib/lib/core/image/sniff.d.ts

@@ -0,0 +1,3 @@
+export type SniffedImageMime = 'image/png' | 'image/jpeg' | 'image/heic' | 'image/avif' | 'image/webp' | 'image/gif' | 'image/bmp' | 'image/tiff';
+export declare function detectImageMime(bytes: Uint8Array): SniffedImageMime | null;
+export declare function mapDeclaredToSniffed(declared: string): SniffedImageMime | null;