@qvac/core 0.0.0 → 0.1.1

package/dist-lib/lib/kv-cache.d.ts

@@ -0,0 +1,18 @@
+import type { Capabilities } from '../spec/capabilities.d.ts';
+export type KvCacheDeletionResult = {
+    status: 'success';
+} | {
+    status: 'failure';
+    error: string;
+} | {
+    status: 'unsupported';
+    error: string;
+};
+interface LegacyCompatibleClient {
+    clearKvCache?: Capabilities['clearKvCache'];
+    deleteChatKvCache?: Capabilities['deleteChatKvCache'];
+    deviceInfo?: Capabilities['deviceInfo'];
+}
+export declare function clearKvCache(client: LegacyCompatibleClient): Promise<KvCacheDeletionResult>;
+export declare function deleteChatKvCache(client: LegacyCompatibleClient, chatId: string): Promise<KvCacheDeletionResult>;
+export {};

package/dist-lib/lib/kv-cache.js

@@ -0,0 +1,33 @@
+export async function clearKvCache(client) {
+    const clear = client.clearKvCache?.bind(client);
+    return deleteWhenSupported(client, clear);
+}
+export async function deleteChatKvCache(client, chatId) {
+    const remove = client.deleteChatKvCache?.bind(client);
+    return deleteWhenSupported(client, remove && (() => remove({ id: chatId })));
+}
+async function deleteWhenSupported(client, deletion) {
+    if (!client.deviceInfo || !deletion)
+        return unsupported();
+    try {
+        const info = await client.deviceInfo();
+        if (info.supportsKvCacheDeletion !== true)
+            return unsupported();
+        const response = await deletion();
+        if (response.status === 'success')
+            return { status: 'success' };
+        if (response.status === 'failure') {
+            return { status: 'failure', error: response.error ?? 'Core KV cache deletion failed' };
+        }
+        return unsupported(response.error);
+    }
+    catch (error) {
+        return {
+            status: 'failure',
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function unsupported(error) {
+    return { status: 'unsupported', error: error ?? 'Core does not support KV cache deletion' };
+}

package/dist-lib/lib/legacy-core-domain.d.ts

@@ -0,0 +1,258 @@
+import type { ImageModelChoice } from '@qvac/harness/model-catalog';
+export type Attachment = {
+    readonly id: string;
+    readonly messageId: string;
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly byteLength: number;
+    readonly blobId: string;
+    readonly createdAt: number;
+};
+export type DelegationCapabilities = {
+    chat: boolean;
+    transcription: boolean;
+    tts: boolean;
+    embeddings: boolean;
+    knowledge: boolean;
+};
+export type DelegationConfig = {
+    enabled: boolean;
+    targetDeviceId: string | null;
+    targetAgentId: string | null;
+    capabilities: DelegationCapabilities;
+};
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | ReadonlyArray<JsonValue>;
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+export type ToolCallData = {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: JsonObject;
+};
+export type ToolCallErrorData = {
+    readonly code: string;
+    readonly message: string;
+};
+export type InferenceMetrics = {
+    readonly ttft: number;
+    readonly tps: number;
+    readonly totalTokens: number;
+    readonly durationMs: number;
+    readonly promptTokens: number | null;
+    readonly cacheTokens: number | null;
+};
+export type RagSourceData = {
+    readonly label: string;
+    readonly fileName: string;
+    readonly chunkIndex: number;
+    readonly excerpt: string;
+    readonly attachmentId: string | null;
+    readonly artifactId: string | null;
+    readonly documentId: string | null;
+    readonly score: number;
+};
+export type ToolApprovalRequest = {
+    readonly id: string;
+    readonly toolCallId?: string | undefined;
+    readonly runId?: string | null | undefined;
+    readonly toolName: string;
+    readonly action?: string | undefined;
+    readonly args: JsonObject;
+};
+export type StreamEvent = {
+    readonly type: 'thinking';
+    readonly token: string;
+} | {
+    readonly type: 'content';
+    readonly token: string;
+} | {
+    readonly type: 'tool-call';
+    readonly call: ToolCallData;
+} | {
+    readonly type: 'tool-call-error';
+    readonly error: ToolCallErrorData;
+} | {
+    readonly type: 'metrics';
+    readonly metrics: InferenceMetrics;
+} | {
+    readonly type: 'tool-approval-request';
+    readonly request: ToolApprovalRequest;
+} | {
+    readonly type: 'tool-exec-start';
+    readonly id: string;
+    readonly command: string;
+} | {
+    readonly type: 'tool-exec-output';
+    readonly id: string;
+    readonly data: string;
+} | {
+    readonly type: 'tool-exec-done';
+    readonly id: string;
+    readonly exitCode: number;
+    readonly durationMs: number;
+} | {
+    readonly type: 'tool-result';
+    readonly id: string;
+    readonly name: string;
+    readonly data: JsonObject;
+} | {
+    readonly type: 'turn-start';
+} | {
+    readonly type: 'model-loading';
+    readonly modelName: string;
+} | {
+    readonly type: 'model-loaded';
+    readonly modelName: string;
+} | {
+    readonly type: 'image-model-loading';
+    readonly choice: ImageModelChoice;
+} | {
+    readonly type: 'image-model-load-progress';
+    readonly choice: ImageModelChoice;
+    readonly downloaded: number;
+    readonly total: number;
+    readonly percentage: number;
+} | {
+    readonly type: 'image-model-loaded';
+    readonly choice: ImageModelChoice;
+    readonly ok: boolean;
+} | {
+    readonly type: 'image-generation-progress';
+    readonly id: string;
+    readonly percentage: number;
+} | {
+    readonly type: 'vision-processing';
+    readonly fileName: string;
+} | {
+    readonly type: 'vision-done';
+} | {
+    readonly type: 'vision-error';
+    readonly fileName: string;
+    readonly reason: string;
+} | {
+    readonly type: 'audio-transcribing';
+    readonly fileName: string;
+} | {
+    readonly type: 'audio-done';
+} | {
+    readonly type: 'ocr-processing';
+    readonly fileName: string;
+} | {
+    readonly type: 'ocr-done';
+    readonly fileName: string;
+    readonly blockCount: number;
+} | {
+    readonly type: 'rag-sources';
+    readonly sources: ReadonlyArray<RagSourceData>;
+} | {
+    readonly type: 'rag-notice';
+    readonly message: string;
+} | {
+    readonly type: 'web-search-start';
+    readonly id: string;
+    readonly query: string;
+} | {
+    readonly type: 'web-search-done';
+    readonly id: string;
+    readonly resultCount: number;
+    readonly engineSummary: ReadonlyArray<{
+        readonly engine: string;
+        readonly status: 'ok' | 'timeout' | 'error';
+        readonly resultCount: number;
+    }>;
+};
+export type LocalStreamEvent = {
+    readonly runId: string;
+    readonly chatId: string;
+    readonly event: StreamEvent;
+};
+export type RemoteStreamEvent = {
+    readonly taskId: string;
+    readonly chatId: string;
+    readonly event: StreamEvent | {
+        readonly type: 'done';
+    };
+    readonly targetDeviceId?: string | undefined;
+};
+export type NetworkAddress = {
+    readonly host: string;
+    readonly port: number;
+};
+export type DhtConnectionStat = {
+    readonly host: string | null;
+    readonly port: number | null;
+    readonly online: boolean | null;
+    readonly degraded: boolean | null;
+    readonly connections: number;
+    readonly peers: ReadonlyArray<string>;
+};
+export type DhtHealthStat = {
+    readonly online: boolean;
+    readonly degraded: boolean;
+    readonly cold: boolean;
+    readonly idle: boolean;
+    readonly responses: number;
+    readonly timeouts: number;
+    readonly timeoutsRate: number;
+};
+export type DhtConfigStat = {
+    readonly concurrency: number;
+    readonly maxWindow: number;
+    readonly randomPunchInterval: number;
+    readonly connectionKeepAlive: number;
+    readonly sendDownHints: boolean;
+    readonly downHintsRateLimit: number;
+};
+export type NetworkStat = {
+    readonly tick: number;
+    readonly localAddress: NetworkAddress | null;
+    readonly remoteAddress: NetworkAddress | null;
+    readonly connection: DhtConnectionStat;
+    readonly stats: Record<string, unknown>;
+    readonly health: DhtHealthStat;
+    readonly nodes: number;
+    readonly config: DhtConfigStat;
+};
+export type ProcessMemoryStat = {
+    readonly percent: number;
+    readonly rss: number;
+    readonly total: number;
+    readonly heapPercent: number;
+    readonly heapUsed: number;
+    readonly heapTotal: number;
+    readonly external: number;
+};
+export type ProcessStat = {
+    readonly timestamp: string;
+    readonly cpu: number;
+    readonly cpuThread: number;
+    readonly cpus: number;
+    readonly memory: ProcessMemoryStat;
+    readonly delay: number;
+    readonly runtime: number;
+};
+export type MeshStat = {
+    readonly head: {
+        readonly key: string;
+        readonly length: number;
+    };
+    readonly system?: {
+        readonly key: string | null;
+        readonly length: number;
+    };
+    readonly flushes?: number;
+    readonly writable: boolean;
+};
+export type MemoryBudgetStat = {
+    readonly totalBytes: number;
+    readonly availableBytes: number;
+    readonly source: string;
+};
+export type ModelEvictionPolicyId = 'single-active' | 'lru' | 'keep-during-turn';
+export type ModelLifecycleConfig = {
+    readonly policy: ModelEvictionPolicyId;
+    readonly cap: number;
+    readonly unloadTimeoutMs?: number;
+};

package/dist-lib/lib/legacy-core-domain.js

@@ -0,0 +1 @@
+export {};

package/dist-lib/lib/llm-model-names.d.ts

@@ -0,0 +1 @@
+export { QWEN_35_2B, QWEN_35_4B, QWEN_35_9B, QWEN_36_27B, QWEN_36_35B_A3B, QWEN_38_27B, MEDPSY_1_7B, MEDPSY_4B } from '@qvac/harness/model-catalog';

package/dist-lib/lib/llm-model-names.js

@@ -0,0 +1 @@
+export { QWEN_35_2B, QWEN_35_4B, QWEN_35_9B, QWEN_36_27B, QWEN_36_35B_A3B, QWEN_38_27B, MEDPSY_1_7B, MEDPSY_4B } from '@qvac/harness/model-catalog';

package/dist-lib/lib/log-buffer.d.ts

@@ -0,0 +1,7 @@
+export declare class LogBuffer<T> {
+    private readonly _items;
+    private readonly _cap;
+    constructor(cap: number);
+    push(item: T): void;
+    snapshot(): ReadonlyArray<T>;
+}

package/dist-lib/lib/log-buffer.js

@@ -0,0 +1,16 @@
+export class LogBuffer {
+    _items;
+    _cap;
+    constructor(cap) {
+        this._items = [];
+        this._cap = cap;
+    }
+    push(item) {
+        this._items.push(item);
+        if (this._items.length > this._cap)
+            this._items.shift();
+    }
+    snapshot() {
+        return [...this._items];
+    }
+}

package/dist-lib/lib/log-levels.d.ts

@@ -0,0 +1,7 @@
+export declare const LEVELS: {
+    debug: number;
+    info: number;
+    warn: number;
+    error: number;
+};
+export type LogLevel = keyof typeof LEVELS;

package/dist-lib/lib/log-levels.js

@@ -0,0 +1 @@
+export const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };

package/dist-lib/lib/log.d.ts

@@ -0,0 +1,60 @@
+import { type LogLevel } from './log-levels.ts';
+export { LEVELS } from './log-levels.ts';
+export type { LogLevel } from './log-levels.ts';
+export type LogOrigin = 'core' | 'client';
+export interface LogRecord {
+    readonly seq: number;
+    readonly at: number;
+    readonly level: LogLevel;
+    readonly scope: ReadonlyArray<string>;
+    readonly message: string;
+    readonly origin: LogOrigin;
+    readonly originDeviceId?: Buffer | undefined;
+}
+export interface LogClientInput {
+    readonly level: LogLevel;
+    readonly scope: ReadonlyArray<string>;
+    readonly message: string;
+    readonly at: number;
+    readonly originDeviceId?: Buffer;
+}
+export interface LoggerOptions {
+    dev?: boolean;
+    verbose?: boolean | undefined;
+    logFile?: string | undefined;
+    logLevel?: LogLevel | undefined;
+    logFileMaxSize?: number;
+}
+export interface LogFlags {
+    logFile?: string | undefined;
+    logLevel?: string | undefined;
+    logVerbose?: boolean | undefined;
+}
+export declare function isLogLevel(value: unknown): value is LogLevel;
+export declare function toLoggerOptions(flags: LogFlags): LoggerOptions;
+export declare class Logger {
+    private _muted;
+    private _dev;
+    private _verbose;
+    private _level;
+    private _system;
+    private _file;
+    private _seq;
+    private readonly _subscribers;
+    private readonly _buffer;
+    constructor({ dev, verbose, logFile, logLevel, logFileMaxSize }?: LoggerOptions);
+    mute(): void;
+    unmute(): void;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    subscribe(listener: (record: LogRecord) => void): void;
+    unsubscribe(listener: (record: LogRecord) => void): void;
+    backfill(): ReadonlyArray<LogRecord>;
+    onRotate(listener: (path: string, archived: string | null) => void): void;
+    close(): void;
+    appendClient(input: LogClientInput): void;
+    _write(level: LogLevel, ...args: unknown[]): void;
+    private _sink;
+}

package/dist-lib/lib/log.js

@@ -0,0 +1,149 @@
+import fs from 'fs';
+import { dirname } from 'path';
+import FileLog from 'bare-file-logger';
+import SystemLog from 'bare-system-logger';
+import { LogBuffer } from "./log-buffer.js";
+import { LEVELS } from "./log-levels.js";
+export { LEVELS } from "./log-levels.js";
+const SCOPE = 'qvac-app-core';
+const LOG_BUFFER_CAP = 1000;
+export function isLogLevel(value) {
+    return typeof value === 'string' && value in LEVELS;
+}
+export function toLoggerOptions(flags) {
+    return {
+        logFile: flags.logFile || undefined,
+        logLevel: isLogLevel(flags.logLevel) ? flags.logLevel : undefined,
+        verbose: flags.logVerbose ? true : undefined
+    };
+}
+export class Logger {
+    _muted;
+    _dev;
+    _verbose;
+    _level;
+    _system;
+    _file;
+    _seq;
+    _subscribers;
+    _buffer;
+    constructor({ dev = false, verbose = false, logFile, logLevel = 'info', logFileMaxSize } = {}) {
+        this._muted = false;
+        this._dev = dev;
+        this._verbose = verbose;
+        this._level = LEVELS[logLevel] ?? LEVELS.info;
+        this._system = new SystemLog();
+        if (logFile)
+            fs.mkdirSync(dirname(logFile), { recursive: true });
+        this._file = logFile
+            ? new FileLog(logFile, {
+                maxSize: logFileMaxSize || 100_000_000,
+                rotate: (path) => `${path}.1`
+            })
+            : null;
+        this._seq = 0;
+        this._subscribers = new Set();
+        this._buffer = new LogBuffer(LOG_BUFFER_CAP);
+    }
+    mute() {
+        this._muted = true;
+    }
+    unmute() {
+        this._muted = false;
+    }
+    debug(...args) {
+        this._write('debug', ...args);
+    }
+    info(...args) {
+        this._write('info', ...args);
+    }
+    warn(...args) {
+        this._write('warn', ...args);
+    }
+    error(...args) {
+        this._write('error', ...args);
+    }
+    subscribe(listener) {
+        this._subscribers.add(listener);
+    }
+    unsubscribe(listener) {
+        this._subscribers.delete(listener);
+    }
+    backfill() {
+        return this._buffer.snapshot();
+    }
+    onRotate(listener) {
+        this._file?.on('rotate', listener);
+    }
+    close() {
+        this._file?.close();
+        this._file = null;
+    }
+    appendClient(input) {
+        if (this._muted)
+            return;
+        this._sink({
+            level: input.level,
+            scope: [...input.scope],
+            message: input.message,
+            origin: 'client',
+            originDeviceId: input.originDeviceId,
+            at: input.at
+        });
+    }
+    _write(level, ...args) {
+        if (this._muted || LEVELS[level] < this._level)
+            return;
+        this._sink({ level, ...toParts(args), origin: 'core', at: Date.now() });
+    }
+    _sink(parts) {
+        const record = { ...parts, seq: this._seq++ };
+        const rendered = renderRecord(record);
+        if (this._verbose || (this._dev && this._level === LEVELS.debug)) {
+            const log = console[record.level] || console.log;
+            log(...rendered);
+        }
+        this._system[record.level](...rendered);
+        if (this._file)
+            this._file[record.level](...rendered);
+        this._buffer.push(record);
+        for (const listener of this._subscribers)
+            listener(record);
+    }
+}
+function renderRecord(record) {
+    const tags = [SCOPE, ...record.scope];
+    if (record.origin === 'client') {
+        tags.push(record.originDeviceId
+            ? `client:${record.originDeviceId.toString('hex').slice(0, 8)}`
+            : 'client');
+    }
+    return [`[${tags.join(':')}]`, new Date(record.at).toISOString(), '-', record.message];
+}
+function toParts(args) {
+    const [rawScope, rawMessage, ...rest] = args;
+    const scope = typeof rawScope === 'string'
+        ? [rawScope]
+        : Array.isArray(rawScope) && rawScope.every((s) => typeof s === 'string')
+            ? [...rawScope]
+            : [];
+    const head = typeof rawMessage === 'string'
+        ? rawMessage
+        : rawMessage === undefined
+            ? ''
+            : formatArg(rawMessage);
+    const tail = rest.map(formatArg).join(' ');
+    return { scope, message: tail ? `${head} ${tail}`.trim() : head };
+}
+function formatArg(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Error)
+        return value.stack ?? value.message;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist-lib/lib/logger-type.d.ts

@@ -0,0 +1,13 @@
+import type { LogClientInput, LogRecord } from './log.ts';
+export interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    mute(): void;
+    unmute(): void;
+    subscribe(listener: (record: LogRecord) => void): void;
+    unsubscribe(listener: (record: LogRecord) => void): void;
+    backfill(): ReadonlyArray<LogRecord>;
+    appendClient(input: LogClientInput): void;
+}

package/dist-lib/lib/logger-type.js

@@ -0,0 +1 @@
+export {};

package/dist-lib/lib/logger.d.ts

@@ -0,0 +1,5 @@
+import type { Logger } from './logger-type.ts';
+declare global {
+    var logger: Logger;
+}
+export declare function setLogger(next: Logger | null): void;

package/dist-lib/lib/logger.js

@@ -0,0 +1,18 @@
+const silent = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+    mute() { },
+    unmute() { },
+    subscribe() { },
+    unsubscribe() { },
+    backfill() {
+        return [];
+    },
+    appendClient() { }
+};
+globalThis.logger ??= silent;
+export function setLogger(next) {
+    globalThis.logger = next ?? silent;
+}

package/dist-lib/lib/model-catalog-revision.d.ts

@@ -0,0 +1,9 @@
+import type { AssistantModelCatalogRevision } from '../spec/hyperschema/types.d.ts';
+export declare class ModelCatalogRevisionHub {
+    private readonly _listeners;
+    private _revision;
+    private _closed;
+    notify(): void;
+    watch(): AsyncIterable<AssistantModelCatalogRevision>;
+    close(): void;
+}

package/dist-lib/lib/model-catalog-revision.js

@@ -0,0 +1,65 @@
+export class ModelCatalogRevisionHub {
+    _listeners = new Set();
+    _revision = 0;
+    _closed = false;
+    notify() {
+        if (this._closed)
+            return;
+        this._revision += 1;
+        for (const listener of this._listeners)
+            listener();
+    }
+    watch() {
+        const hub = this;
+        let observed = -1;
+        let ended = false;
+        let pending = null;
+        const done = () => ({
+            value: undefined,
+            done: true
+        });
+        const onChange = () => {
+            if (!pending)
+                return;
+            const next = pending;
+            pending = null;
+            if (ended || hub._closed) {
+                next.resolve(done());
+                return;
+            }
+            observed = hub._revision;
+            next.resolve({ value: { revision: observed }, done: false });
+        };
+        hub._listeners.add(onChange);
+        const iterator = {
+            next() {
+                if (ended || hub._closed)
+                    return Promise.resolve(done());
+                if (observed !== hub._revision) {
+                    observed = hub._revision;
+                    return Promise.resolve({ value: { revision: observed }, done: false });
+                }
+                pending ??= Promise.withResolvers();
+                return pending.promise;
+            },
+            return() {
+                ended = true;
+                hub._listeners.delete(onChange);
+                pending?.resolve(done());
+                pending = null;
+                return Promise.resolve(done());
+            }
+        };
+        return {
+            [Symbol.asyncIterator]: () => iterator
+        };
+    }
+    close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        for (const listener of this._listeners)
+            listener();
+        this._listeners.clear();
+    }
+}

package/dist-lib/lib/model-clamp.d.ts

@@ -0,0 +1,6 @@
+export interface HostCapability {
+    readonly capabilityProfile: string;
+    readonly recommendedModelName: string;
+}
+export declare function isMobilePlatform(platform: string): boolean;
+export declare function runnableModelName(requested: string, host: HostCapability | null, mobileClass: boolean): string;