@qvac/core 0.0.0 → 0.1.1

package/dist-lib/lib/core/skill-overlay-receiver.js

@@ -0,0 +1,20 @@
+import b4a from 'b4a';
+import { getAgent } from "./agent.js";
+import { NO_SUCH_AGENT, NOT_THE_HOST, SENDER_REVOKED } from "./skill-secrets.js";
+const DEVICES = '@qvac/devices';
+export function createSkillOverlayReceiver(opts) {
+    return async (op, fromDeviceId) => {
+        const sender = await opts.mesh.view.get(DEVICES, { id: fromDeviceId });
+        if (!sender || sender.revoked)
+            throw new Error(SENDER_REVOKED);
+        if (!op.agentId)
+            throw new Error(NO_SUCH_AGENT);
+        const agent = await getAgent(opts.mesh, op.agentId);
+        if (!agent)
+            throw new Error(NO_SUCH_AGENT);
+        if (!agent.providerDeviceId || !b4a.equals(agent.providerDeviceId, opts.deviceId)) {
+            throw new Error(NOT_THE_HOST);
+        }
+        return opts.runLocal(op);
+    };
+}

package/dist-lib/lib/core/skill-secrets.d.ts

@@ -0,0 +1,25 @@
+import type { AssistantSkill } from '../../spec/hyperschema/types.d.ts';
+import type { QvacAgent } from '../../spec/mesh/hyperschema/types.d.ts';
+import type { openLocalStore } from './local/index.ts';
+import type { Mesh } from './mesh.ts';
+import type { SecretRequestHandler } from './secret-handoff.ts';
+export declare const NOT_THE_HOST = "this device does not host that agent";
+export declare const SENDER_REVOKED = "the sending device is no longer in the mesh";
+export declare const HOST_REVOKED = "the device hosting this agent is no longer in the mesh";
+export declare const NO_SUCH_AGENT = "no agent with that id";
+export declare const NOT_A_SETUP_FIELD = "that skill declares no such setup field";
+export type SetupFields = (skillName: string) => Promise<ReadonlyMap<string, boolean> | null>;
+export interface SkillSecretsOptions {
+    readonly mesh: Mesh;
+    readonly local: ReturnType<typeof openLocalStore>;
+    readonly deviceId: Uint8Array;
+    readonly setupFields: SetupFields;
+    readonly onstored: () => Promise<unknown>;
+}
+export declare function createSkillSecretReceiver(opts: SkillSecretsOptions): SecretRequestHandler;
+export interface SkillValue {
+    readonly skillName: string;
+    readonly key: string;
+    readonly storageKey: string;
+}
+export declare function agentSkillValues(catalog: ReadonlyArray<AssistantSkill>, agent: Pick<QvacAgent, 'id' | 'installedSkills' | 'enabledSkills'>): ReadonlyArray<SkillValue>;

package/dist-lib/lib/core/skill-secrets.js

@@ -0,0 +1,79 @@
+import b4a from 'b4a';
+import { credentialSlots } from '@qvac/harness/lib/tools/skills/credential-slots.ts';
+import { isDeviceSharedCredentialKey } from '@qvac/harness/lib/tools/skills/scope-key.ts';
+import { oauthStateKey, settingConfigKey } from "../credential-pusher.js";
+import { scopedKey } from "../oauth/common.js";
+import { getAgent } from "./agent.js";
+const DEVICES = '@qvac/devices';
+export const NOT_THE_HOST = 'this device does not host that agent';
+export const SENDER_REVOKED = 'the sending device is no longer in the mesh';
+export const HOST_REVOKED = 'the device hosting this agent is no longer in the mesh';
+export const NO_SUCH_AGENT = 'no agent with that id';
+export const NOT_A_SETUP_FIELD = 'that skill declares no such setup field';
+export function createSkillSecretReceiver(opts) {
+    return async (request, fromDeviceId) => {
+        const sender = await opts.mesh.view.get(DEVICES, { id: fromDeviceId });
+        if (!sender || sender.revoked)
+            throw new Error(SENDER_REVOKED);
+        const agent = await getAgent(opts.mesh, request.agentId);
+        if (!agent)
+            throw new Error(NO_SUCH_AGENT);
+        if (!agent.providerDeviceId || !b4a.equals(agent.providerDeviceId, opts.deviceId)) {
+            throw new Error(NOT_THE_HOST);
+        }
+        const fields = await opts.setupFields(request.skillName);
+        if (fields && request.values.some(({ key }) => !fields.has(key))) {
+            throw new Error(NOT_A_SETUP_FIELD);
+        }
+        const entries = request.values.map(({ key, value }) => ({
+            key: fields?.get(key) === false
+                ? settingConfigKey(undefined, request.skillName, key)
+                : scopedKey(isDeviceSharedCredentialKey(key) ? undefined : request.agentId, key),
+            value
+        }));
+        if (entries.length === 0)
+            return;
+        await opts.local.setAll(entries);
+        await opts.onstored();
+    };
+}
+export function agentSkillValues(catalog, agent) {
+    const installed = new Set([...(agent.installedSkills ?? []), ...(agent.enabledSkills ?? [])]);
+    const values = new Map();
+    for (const skill of catalog) {
+        if (!installed.has(skill.name))
+            continue;
+        for (const key of credentialKeys(skill)) {
+            if (isDeviceSharedCredentialKey(key))
+                continue;
+            const storageKey = scopedKey(agent.id, key);
+            values.set(storageKey, { skillName: skill.name, key, storageKey });
+        }
+    }
+    return [...values.values()];
+}
+function credentialKeys(skill) {
+    const keys = new Set();
+    const slots = credentialSlots({
+        credentials: skill.credentials ?? undefined,
+        requires: { credentials: skill.requirements?.credentials ?? undefined }
+    });
+    for (const slot of slots) {
+        for (const key of slot)
+            keys.add(key);
+    }
+    for (const route of skill.setup?.routes ?? []) {
+        if (route.credentialKey)
+            keys.add(route.credentialKey);
+        for (const field of route.fields ?? []) {
+            if (field.secret === true)
+                keys.add(field.key);
+        }
+    }
+    for (const key of [...keys]) {
+        const state = oauthStateKey(key);
+        if (state)
+            keys.add(state);
+    }
+    return [...keys];
+}

package/dist-lib/lib/core/sync/chats.d.ts

@@ -0,0 +1,3 @@
+import type { QvacChat } from '../../../spec/mesh/hyperschema/types';
+import type { Mesh } from '../mesh.ts';
+export declare function syncChatTombstone(mesh: Mesh, chat: QvacChat): void;

package/dist-lib/lib/core/sync/chats.js

@@ -0,0 +1,5 @@
+export function syncChatTombstone(mesh, chat) {
+    if (!chat.deletedAt)
+        return;
+    mesh.emit('chat-tombstone', chat.id, chat.deletedAt);
+}

package/dist-lib/lib/core/sync/chunks.d.ts

@@ -0,0 +1,9 @@
+import type { QvacChunk } from '../../../spec/mesh/hyperschema/types';
+import type { Mesh } from '../mesh';
+export interface NotificationEvent {
+    readonly chatId: string;
+    readonly chunkId: string;
+    readonly seq: number;
+    readonly type: 'run-status' | 'approval-request' | 'user-message';
+}
+export declare function syncNotificationChunk(mesh: Mesh, chunk: QvacChunk): void;

package/dist-lib/lib/core/sync/chunks.js

@@ -0,0 +1,16 @@
+export function syncNotificationChunk(mesh, chunk) {
+    if (chunk.type === 'run-status') {
+        const state = chunk.runStatus?.state;
+        if (state !== 'completed' && state !== 'failed')
+            return;
+    }
+    else if (chunk.type !== 'approval-request' && chunk.type !== 'user-message') {
+        return;
+    }
+    mesh.emit('notification', {
+        chatId: chunk.chatId,
+        chunkId: chunk.id,
+        seq: chunk.seq,
+        type: chunk.type
+    });
+}

package/dist-lib/lib/core/sync/devices.d.ts

@@ -0,0 +1,4 @@
+import type { QvacDevice } from '../../../spec/mesh/hyperschema/types';
+import type { Mesh } from '../mesh.ts';
+export declare function syncOwnMember(mesh: Mesh, device: QvacDevice): void;
+export declare function syncDeviceRevocation(mesh: Mesh, device: QvacDevice): void;

package/dist-lib/lib/core/sync/devices.js

@@ -0,0 +1,12 @@
+import { isOwnKickedRow } from "../helpers/index.js";
+export function syncOwnMember(mesh, device) {
+    if (!device.writerKey?.equals(mesh.localWriterKey))
+        return;
+    void mesh.refreshOurMember();
+}
+export function syncDeviceRevocation(mesh, device) {
+    if (!isOwnKickedRow(mesh, device))
+        return;
+    logger.info('sync', 'our writer was revoked (kicked)');
+    mesh.emit('kicked');
+}

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

@@ -0,0 +1,16 @@
+import type HyperDB from 'hyperdb';
+import type { ViewChange } from 'hyperdb';
+export declare class FileChanges {
+    private readonly _snap;
+    private readonly _from;
+    private readonly _documents;
+    private readonly _chats;
+    private readonly _agents;
+    private readonly _devices;
+    constructor(snap: HyperDB, from: {
+        key: Buffer;
+        length: number;
+    });
+    add(change: ViewChange): Promise<void>;
+    ids(): Promise<Set<string>>;
+}

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

@@ -0,0 +1,109 @@
+import b4a from 'b4a';
+import { toolsetEnabled } from '@qvac/harness/lib/tools/toolsets.ts';
+export class FileChanges {
+    _snap;
+    _from;
+    _documents = new Set();
+    _chats = new Set();
+    _agents = new Set();
+    _devices = new Set();
+    constructor(snap, from) {
+        this._snap = snap;
+        this._from = from;
+    }
+    async add(change) {
+        const { collection, value } = change;
+        const query = { id: value.id };
+        const previous = { checkout: this._from };
+        switch (collection) {
+            case '@qvac/chunks': {
+                const chunk = await this._snap.get(collection, query);
+                if (chunk?.attachment && chunk.id === chunk.attachment.id)
+                    this._documents.add(chunk.id);
+                break;
+            }
+            case '@qvac/knowledge':
+                if (typeof value.id === 'string')
+                    this._documents.add(value.id);
+                break;
+            case '@qvac/knowledge-artifacts':
+            case '@qvac/indexing-status': {
+                const row = change.type === 'delete' ? await this._snap.get(collection, query, previous) : value;
+                if (typeof row?.knowledgeId === 'string')
+                    this._documents.add(row.knowledgeId);
+                break;
+            }
+            case '@qvac/chats': {
+                const before = await this._snap.get(collection, query, previous);
+                const after = await this._snap.get(collection, query);
+                if (!before ||
+                    !after ||
+                    before.agentId !== after.agentId ||
+                    !!before.deletedAt !== !!after.deletedAt) {
+                    const row = after ?? before;
+                    if (row)
+                        this._chats.add(row.id);
+                }
+                break;
+            }
+            case '@qvac/agents': {
+                const before = await this._snap.get(collection, query, previous);
+                const after = await this._snap.get(collection, query);
+                if (!before ||
+                    !after ||
+                    !b4a.equals(before.providerDeviceId, after.providerDeviceId) ||
+                    !!before.deletedAt !== !!after.deletedAt ||
+                    toolsetEnabled('knowledge', before.disabledToolsets) !==
+                        toolsetEnabled('knowledge', after.disabledToolsets)) {
+                    const row = after ?? before;
+                    if (row)
+                        this._agents.add(row.id);
+                }
+                break;
+            }
+            case '@qvac/devices': {
+                const before = await this._snap.get(collection, query, previous);
+                const after = await this._snap.get(collection, query);
+                if (!before || !after || !!before.revoked !== !!after.revoked) {
+                    const row = after ?? before;
+                    if (row)
+                        this._devices.add(b4a.toString(row.id, 'hex'));
+                }
+                break;
+            }
+        }
+    }
+    async ids() {
+        if (this._devices.size) {
+            for await (const agent of this._snap.find('@qvac/agents')) {
+                if (this._devices.has(b4a.toString(agent.providerDeviceId, 'hex'))) {
+                    this._agents.add(agent.id);
+                }
+            }
+        }
+        for (const agentId of this._agents) {
+            for await (const chat of this._snap.find('@qvac/active-chats-by-agent', {
+                gte: { agentId },
+                lte: { agentId }
+            })) {
+                this._chats.add(chat.id);
+            }
+        }
+        for (const chatId of this._chats) {
+            for await (const document of this._snap.find('@qvac/knowledge-by-chat', {
+                gte: { chatId },
+                lte: { chatId }
+            })) {
+                this._documents.add(document.id);
+            }
+            for await (const chunk of this._snap.find('@qvac/chunks-by-chat', {
+                gte: { chatId },
+                lte: { chatId }
+            })) {
+                if (chunk.attachment && chunk.id === chunk.attachment.id)
+                    this._documents.add(chunk.id);
+            }
+        }
+        return this._documents;
+    }
+}

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

@@ -0,0 +1,5 @@
+import type { Mesh, MeshView } from '../mesh.ts';
+export declare function syncChanges(mesh: Mesh, view: MeshView, from: {
+    key: Buffer;
+    length: number;
+}): Promise<void>;

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

@@ -0,0 +1,63 @@
+import { FileChanges } from "./files.js";
+import { syncDeviceRevocation, syncOwnMember } from "./devices.js";
+import { syncChatTombstone } from "./chats.js";
+import { syncNotificationChunk } from "./chunks.js";
+export async function syncChanges(mesh, view, from) {
+    if (mesh.closing)
+        return;
+    let indexingDirty = new Set();
+    let unattestedDevice = false;
+    let membershipMoved = false;
+    let agentsDirty = false;
+    const snap = view.db.snapshot();
+    const files = new FileChanges(snap, from);
+    try {
+        for await (const change of snap.changes({ from })) {
+            if (mesh.closing)
+                return;
+            await files.add(change);
+            switch (change.collection) {
+                case '@qvac/devices': {
+                    membershipMoved = true;
+                    const device = change.value;
+                    if (!device.revoked && !device.memberId)
+                        unattestedDevice = true;
+                    syncOwnMember(mesh, device);
+                    syncDeviceRevocation(mesh, device);
+                    break;
+                }
+                case '@qvac/members':
+                    membershipMoved = true;
+                    break;
+                case '@qvac/agents':
+                    agentsDirty = true;
+                    break;
+                case '@qvac/chats':
+                    syncChatTombstone(mesh, change.value);
+                    break;
+                case '@qvac/chunks':
+                    syncNotificationChunk(mesh, change.value);
+                    await mesh.files.syncAttachment(change.value);
+                    break;
+                case '@qvac/knowledge':
+                    await mesh.files.syncKnowledge(change.value);
+                    break;
+                case '@qvac/knowledge-artifacts':
+                    await mesh.files.syncArtifact(change.value);
+                    break;
+            }
+        }
+        indexingDirty = await files.ids();
+    }
+    finally {
+        await snap.close();
+    }
+    if (indexingDirty.size)
+        mesh.emit('indexing-dirty', indexingDirty);
+    if (unattestedDevice)
+        mesh.emit('unattested-device');
+    if (membershipMoved)
+        await mesh.refreshMembership();
+    if (agentsDirty)
+        mesh.emit('agents-dirty');
+}

package/dist-lib/lib/core/sync-status.d.ts

@@ -0,0 +1,17 @@
+import type { AssistantSyncStatus } from '../../spec/hyperschema/types.d.ts';
+import type { Mesh } from './mesh.ts';
+export interface SyncActivity {
+    watch(listener: () => void): void;
+    unwatch(listener: () => void): void;
+    once(event: 'close', listener: () => void): unknown;
+    off(event: 'close', listener: () => void): unknown;
+    readonly closing: unknown;
+    readonly closed: boolean;
+    readonly hold: SyncHold;
+    snapshot(): Promise<AssistantSyncStatus>;
+}
+export interface SyncHold {
+    keep(busy: boolean): boolean;
+}
+export declare function createSyncActivity(mesh: Mesh): SyncActivity;
+export declare function syncStatusSnapshot(mesh: Mesh): Promise<AssistantSyncStatus>;

package/dist-lib/lib/core/sync-status.js

@@ -0,0 +1,129 @@
+import { unref } from "../unref.js";
+const DEVICES = '@qvac/devices';
+const MIN_SYNCING_MS = 1000;
+export function createSyncActivity(mesh) {
+    const listeners = new Set();
+    const notify = () => {
+        for (const listener of [...listeners])
+            listener();
+    };
+    const track = (writer) => {
+        writer.core.on('append', notify);
+        writer.core.on('download', notify);
+    };
+    mesh.watch(notify);
+    mesh.autobee.on('writer', (writer) => track(writer));
+    for (const writer of mesh.autobee.activeWriters)
+        track(writer);
+    mesh.autobee.local.on('upload', notify);
+    mesh.autobee.local.on('peer-remove', notify);
+    return {
+        watch: (listener) => void listeners.add(listener),
+        unwatch: (listener) => void listeners.delete(listener),
+        once: (event, listener) => mesh.once(event, listener),
+        off: (event, listener) => mesh.off(event, listener),
+        get closing() {
+            return mesh.closing;
+        },
+        get closed() {
+            return mesh.closed;
+        },
+        hold: createSyncHold(notify),
+        snapshot: () => syncStatusSnapshot(mesh)
+    };
+}
+function createSyncHold(notify) {
+    let busyUntil = 0;
+    let timer = null;
+    return {
+        keep(busy) {
+            if (busy) {
+                busyUntil = Date.now() + MIN_SYNCING_MS;
+                return true;
+            }
+            const remaining = busyUntil - Date.now();
+            if (remaining <= 0) {
+                return false;
+            }
+            if (timer === null) {
+                timer = setTimeout(() => {
+                    timer = null;
+                    notify();
+                }, remaining);
+                unref(timer);
+            }
+            return true;
+        }
+    };
+}
+export async function syncStatusSnapshot(mesh) {
+    const deviceByWriter = await writerDeviceMap(mesh);
+    const localKey = mesh.autobee.local.key;
+    const sessions = openWriterSessions(mesh);
+    const remoteWriters = [...new Set([...deviceByWriter.keys(), ...sessions.keys()])]
+        .map((hex) => {
+        const session = sessions.get(hex);
+        const device = deviceByWriter.get(hex);
+        return { session, device, writerKey: session ? session.core.key : device.writerKey };
+    })
+        .filter((writer) => !writer.writerKey.equals(localKey));
+    const rows = await Promise.all(remoteWriters.map(async ({ session, device, writerKey }) => {
+        const info = await mesh.autobee.system.get(writerKey, { unflushed: true });
+        return {
+            device,
+            writerKey,
+            info,
+            length: session?.core.length ?? 0,
+            contiguousLength: session?.core.contiguousLength ?? 0
+        };
+    }));
+    const devices = [];
+    let pendingOps = 0;
+    for (const { device, writerKey, info, length, contiguousLength } of rows) {
+        if (info?.isRemoved)
+            continue;
+        const known = Math.max(info?.length ?? 0, length);
+        const applied = Math.max(info?.length ?? 0, contiguousLength);
+        pendingOps += Math.max(0, known - applied);
+        devices.push({
+            writerKey,
+            ...(device ? { deviceId: device.id } : null),
+            applied,
+            known
+        });
+    }
+    const pendingUploads = mesh.pendingUploads();
+    const syncing = mesh.syncActivity.hold.keep(pendingOps + pendingUploads > 0);
+    return {
+        state: statusState(devices.length, syncing),
+        pendingOps,
+        pendingUploads,
+        devices
+    };
+}
+function statusState(writerCount, syncing) {
+    if (writerCount === 0)
+        return 'idle';
+    return syncing ? 'syncing' : 'synced';
+}
+function openWriterSessions(mesh) {
+    const sessions = new Map();
+    for (const writer of mesh.autobee.activeWriters) {
+        sessions.set(writer.core.key.toString('hex'), writer);
+    }
+    return sessions;
+}
+async function writerDeviceMap(mesh) {
+    const map = new Map();
+    const snap = mesh.view.snapshot();
+    try {
+        for await (const device of snap.find(DEVICES)) {
+            if (device.writerKey && !device.revoked)
+                map.set(device.writerKey.toString('hex'), device);
+        }
+    }
+    finally {
+        await snap.close();
+    }
+    return map;
+}

package/dist-lib/lib/core/system-info.d.ts

@@ -0,0 +1,24 @@
+import type CPUInfo from 'bare-cpu-info';
+import type { Drivers, GPU, Usage as GpuUsage } from 'bare-gpu-info';
+import '../logger.ts';
+export type CpuQuery = ReturnType<CPUInfo['query']>;
+export type CpuUsage = ReturnType<CPUInfo['sample']>;
+export type CpuDiagnostics = CpuQuery & {
+    readonly usage: CpuUsage;
+};
+export type GpuDeviceDiagnostics = GPU & {
+    readonly usage: GpuUsage;
+};
+export interface GpuDiagnostics {
+    readonly drivers: Drivers;
+    readonly devices: ReadonlyArray<GpuDeviceDiagnostics>;
+}
+export interface SystemInfoSnapshot {
+    readonly cpu: CpuDiagnostics | null;
+    readonly gpu: GpuDiagnostics | null;
+}
+export interface SystemInfoSampler {
+    snapshot(): SystemInfoSnapshot;
+    destroy(): void;
+}
+export declare function createSystemInfoSampler(): SystemInfoSampler;

package/dist-lib/lib/core/system-info.js

@@ -0,0 +1,66 @@
+import CPUInfoCtor from '#cpu-info';
+import GPUInfoCtor from '#gpu-info';
+import "../logger.js";
+const LOG_TAG = ['diagnostics', 'system-info'];
+function readCpu(cpu) {
+    try {
+        return { ...cpu.query(), usage: cpu.sample() };
+    }
+    catch (err) {
+        logger.warn(LOG_TAG, 'cpu sample failed', err);
+        return null;
+    }
+}
+function readGpu(gpu) {
+    try {
+        const drivers = gpu.drivers();
+        const devices = [];
+        for (let i = 0; i < gpu.length; i++) {
+            try {
+                devices.push({ ...gpu.gpu(i), usage: gpu.sample(i) });
+            }
+            catch (err) {
+                logger.warn(LOG_TAG, `gpu device ${i} sample failed`, err);
+            }
+        }
+        return { drivers, devices };
+    }
+    catch (err) {
+        logger.warn(LOG_TAG, 'gpu drivers query failed', err);
+        return null;
+    }
+}
+export function createSystemInfoSampler() {
+    let cpu = null;
+    let gpu = null;
+    try {
+        if (CPUInfoCtor)
+            cpu = new CPUInfoCtor();
+    }
+    catch (err) {
+        logger.warn(LOG_TAG, 'bare-cpu-info constructor failed', err);
+        cpu = null;
+    }
+    try {
+        if (GPUInfoCtor)
+            gpu = new GPUInfoCtor();
+    }
+    catch (err) {
+        logger.warn(LOG_TAG, 'bare-gpu-info constructor failed', err);
+        gpu = null;
+    }
+    return {
+        snapshot() {
+            return {
+                cpu: cpu ? readCpu(cpu) : null,
+                gpu: gpu ? readGpu(gpu) : null
+            };
+        },
+        destroy() {
+            cpu?.destroy();
+            gpu?.destroy();
+            cpu = null;
+            gpu = null;
+        }
+    };
+}

package/dist-lib/lib/core/tool-activity.d.ts

@@ -0,0 +1,22 @@
+import type { QvacResourceDescriptor, QvacToolActivity, QvacToolDecision } from '../../spec/mesh/hyperschema/types.d.ts';
+import type { Mesh } from './mesh.ts';
+export interface ToolActivityInput {
+    readonly agentId: string;
+    readonly originDeviceId: Buffer;
+    readonly toolName: string;
+    readonly decision: QvacToolDecision;
+    readonly effect?: string;
+    readonly arguments?: unknown;
+    readonly resource?: QvacResourceDescriptor | null;
+    readonly chatId?: string;
+    readonly runId?: string;
+    readonly at: number;
+}
+export declare function recordToolActivity(store: Mesh, input: ToolActivityInput): Promise<{
+    id: string;
+}>;
+export interface ListToolActivityOptions {
+    readonly limit?: number;
+    readonly beforeSeq?: number;
+}
+export declare function listToolActivity(store: Mesh, agentId: string, { limit, beforeSeq }?: ListToolActivityOptions): Promise<QvacToolActivity[]>;