@qvac/core 0.0.0 → 0.1.0

package/dist-lib/lib/credential-pusher.d.ts

@@ -0,0 +1,67 @@
+import type { Harness } from './assistant.ts';
+import { type ConfigEngine } from './oauth.ts';
+export type CredentialEntry = {
+    key: string;
+    token?: string | null;
+    expiresAt?: number | null;
+    agentId?: string | null;
+    skill?: string | null;
+};
+export type SettingEntry = {
+    skill: string;
+    key: string;
+    value: string;
+    agentId?: string | null;
+};
+export type PusherSkill = {
+    name: string;
+    credentials?: readonly string[];
+    requires?: {
+        credentials?: readonly string[];
+    };
+    setup?: {
+        routes?: ReadonlyArray<{
+            fields?: ReadonlyArray<{
+                key: string;
+                secret?: boolean;
+            }>;
+        }>;
+    };
+};
+export interface CredentialEngine extends ConfigEngine {
+    configWatch(req: {
+        key: string;
+    }): AsyncIterable<unknown> & {
+        destroy(): void;
+    };
+    listAgents(req: {}): Promise<{
+        agents: ReadonlyArray<{
+            id: string;
+        }>;
+    }>;
+}
+export type CredentialTarget = {
+    setCredentials: NonNullable<Harness['setCredentials']>;
+    setSkillSettings?: (entries: ReadonlyArray<SettingEntry>) => void | Promise<void>;
+    skills?: (agentId?: string | null, modelName?: string | null, options?: {
+        readonly skipCredentialProbe?: boolean;
+    }) => Promise<ReadonlyArray<PusherSkill>>;
+};
+export type CredentialPusherLogger = {
+    warn(...args: unknown[]): void;
+};
+export type CredentialPusherHandle = (() => Promise<void>) & {
+    sync(): Promise<void>;
+};
+export declare function oauthStateKeyFor(credentialKey: string): string | null;
+export declare function nextRefreshDelay(entries: ReadonlyArray<{
+    expiresAt?: number | null;
+}>, now?: number): number;
+export declare function credentialOwners(catalog: ReadonlyArray<PusherSkill>): ReadonlyMap<string, readonly string[]>;
+export declare function settingFields(catalog: ReadonlyArray<PusherSkill>): ReadonlyArray<{
+    skill: string;
+    key: string;
+}>;
+export declare function settingConfigKey(agentId: string | undefined, skill: string, key: string): string;
+export declare function oauthStateKey(credentialKey: string): string | undefined;
+export declare function startCredentialPusher(harness: CredentialTarget, engine: CredentialEngine, logger?: CredentialPusherLogger | null): CredentialPusherHandle;

package/dist-lib/lib/credential-pusher.js

@@ -0,0 +1,290 @@
+import { OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY } from "./obsidian-key.js";
+import { resolveAsanaCredential, resolveGoogleCredential, resolveNotionCredential, resolveSpotifyCredential, scopedKey } from "./oauth.js";
+import { OAUTH_KEY_SPECS, oauthStateKeyFor as specStateKeyFor } from "./oauth/keys.js";
+import ScopeLock from 'scope-lock';
+import { credentialSlots } from '@qvac/harness/lib/tools/skills/credential-slots.ts';
+import { REFRESH_SKEW_MS } from "./oauth/common.js";
+const RESOLVE_BY_PROVIDER = {
+    google: resolveGoogleCredential,
+    spotify: resolveSpotifyCredential,
+    notion: resolveNotionCredential,
+    asana: resolveAsanaCredential
+};
+export function oauthStateKeyFor(credentialKey) {
+    return specStateKeyFor(credentialKey);
+}
+const PLAIN_KEYS = ['github_access_token', OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY];
+const REFRESH_INTERVAL = 10 * 60 * 1000;
+const MIN_REFRESH_DELAY = 30_000;
+function storeKey(key, agentId) {
+    return agentId ? `${agentId}\0${key}` : key;
+}
+export function nextRefreshDelay(entries, now = Date.now()) {
+    let nearest = null;
+    for (const entry of entries) {
+        if (typeof entry.expiresAt === 'number' && entry.expiresAt > 0) {
+            if (nearest === null || entry.expiresAt < nearest)
+                nearest = entry.expiresAt;
+        }
+    }
+    if (nearest === null)
+        return REFRESH_INTERVAL;
+    return Math.min(REFRESH_INTERVAL, Math.max(MIN_REFRESH_DELAY, nearest - now - REFRESH_SKEW_MS));
+}
+async function oauthEntry(engine, { credentialKey, stateKey, provider }, agentId) {
+    const resolve = RESOLVE_BY_PROVIDER[provider];
+    const token = await resolve({ engine, agentId, credentialKey, stateKey });
+    if (!token)
+        return null;
+    const { value } = await engine.configGet({
+        key: scopedKey(agentId, stateKey)
+    });
+    let expiresAt;
+    try {
+        const state = typeof value === 'string' ? JSON.parse(value) : null;
+        expiresAt = typeof state?.expiresAt === 'number' ? state.expiresAt : undefined;
+    }
+    catch { }
+    return {
+        key: credentialKey,
+        token,
+        ...(expiresAt === undefined ? {} : { expiresAt }),
+        ...(agentId ? { agentId } : {})
+    };
+}
+async function plainEntry(engine, key, agentId) {
+    const { value } = await engine.configGet({ key: scopedKey(agentId, key) });
+    if (typeof value !== 'string' || value === '')
+        return null;
+    return {
+        key,
+        token: value,
+        ...(agentId ? { agentId } : {})
+    };
+}
+export function credentialOwners(catalog) {
+    const owners = new Map();
+    for (const skill of catalog) {
+        for (const key of credentialSlots(skill).flat()) {
+            const list = owners.get(key) ?? [];
+            if (!list.includes(skill.name))
+                list.push(skill.name);
+            owners.set(key, list);
+        }
+    }
+    return owners;
+}
+export function settingFields(catalog) {
+    const fields = [];
+    for (const skill of catalog) {
+        for (const route of skill.setup?.routes ?? []) {
+            for (const field of route.fields ?? []) {
+                if (field.secret === true)
+                    continue;
+                if (fields.some((f) => f.skill === skill.name && f.key === field.key))
+                    continue;
+                fields.push({ skill: skill.name, key: field.key });
+            }
+        }
+    }
+    return fields;
+}
+export function settingConfigKey(agentId, skill, key) {
+    return scopedKey(agentId, `settings.${skill}.${key}`);
+}
+export function oauthStateKey(credentialKey) {
+    return specStateKeyFor(credentialKey) ?? undefined;
+}
+function fanOut(entry, owners) {
+    const skills = owners.get(entry.key) ?? [];
+    return skills.length > 0 ? skills.map((skill) => ({ ...entry, skill })) : [entry];
+}
+async function resolveScope(engine, agentId, last, owners, logger) {
+    const entries = [];
+    for (const spec of OAUTH_KEY_SPECS) {
+        const mk = storeKey(spec.credentialKey, agentId);
+        try {
+            const entry = await oauthEntry(engine, spec, agentId);
+            if (entry) {
+                last.set(mk, entry);
+                entries.push(...fanOut(entry, owners));
+            }
+            else {
+                last.delete(mk);
+            }
+        }
+        catch (err) {
+            logger?.warn('credential-pusher', `credential resolve failed for ${spec.credentialKey}`, errorMessage(err));
+            const kept = last.get(mk);
+            if (kept)
+                entries.push(...fanOut(kept, owners));
+        }
+    }
+    for (const key of PLAIN_KEYS) {
+        const mk = storeKey(key, agentId);
+        try {
+            const entry = await plainEntry(engine, key, agentId);
+            if (entry) {
+                last.set(mk, entry);
+                entries.push(...fanOut(entry, owners));
+            }
+            else {
+                last.delete(mk);
+            }
+        }
+        catch (err) {
+            logger?.warn('credential-pusher', `credential read failed for ${key}`, errorMessage(err));
+            const kept = last.get(mk);
+            if (kept)
+                entries.push(...fanOut(kept, owners));
+        }
+    }
+    return entries;
+}
+async function resolveSettings(engine, scopes, catalog, logger) {
+    const fields = settingFields(catalog);
+    if (fields.length === 0)
+        return [];
+    const resolved = await Promise.all(scopes.flatMap((agentId) => fields.map(async ({ skill, key }) => {
+        try {
+            const { value } = await engine.configGet({ key: settingConfigKey(agentId, skill, key) });
+            if (typeof value !== 'string' || value === '')
+                return null;
+            return { skill, key, value, ...(agentId ? { agentId } : {}) };
+        }
+        catch (err) {
+            logger?.warn('credential-pusher', `setting read failed for ${skill}.${key}`, errorMessage(err));
+            return null;
+        }
+    })));
+    const entries = [];
+    for (const entry of resolved) {
+        if (entry)
+            entries.push(entry);
+    }
+    return entries;
+}
+export function startCredentialPusher(harness, engine, logger) {
+    const last = new Map();
+    const watches = [];
+    let disposed = false;
+    let timer = null;
+    const pushLock = new ScopeLock({ debounce: true });
+    const armTimer = (delay) => {
+        if (disposed)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            schedule();
+        }, delay);
+    };
+    const catalog = async () => {
+        if (!harness.skills)
+            return [];
+        try {
+            return await harness.skills(null, null, { skipCredentialProbe: true });
+        }
+        catch (err) {
+            logger?.warn('credential-pusher', 'skill catalog read failed', errorMessage(err));
+            return [];
+        }
+    };
+    const pushAll = async () => {
+        const entries = [];
+        try {
+            const skills = await catalog();
+            const owners = credentialOwners(skills);
+            const ids = (await engine.listAgents({})).agents.map((agent) => agent.id);
+            const scopes = [undefined, ...ids];
+            for (const agentId of scopes) {
+                entries.push(...(await resolveScope(engine, agentId, last, owners, logger)));
+            }
+            if (disposed)
+                return;
+            await harness.setCredentials(entries);
+            if (harness.setSkillSettings) {
+                await harness.setSkillSettings(await resolveSettings(engine, scopes, skills, logger));
+            }
+        }
+        finally {
+            if (!disposed)
+                armTimer(nextRefreshDelay(entries));
+        }
+    };
+    const schedule = async () => {
+        if (disposed)
+            return;
+        if (!(await pushLock.lock()))
+            return;
+        try {
+            if (!disposed)
+                await pushAll();
+        }
+        catch (err) {
+            logger?.warn('credential-pusher', 'credential push failed', errorMessage(err));
+        }
+        finally {
+            pushLock.unlock();
+        }
+    };
+    const sync = async () => {
+        if (disposed)
+            return;
+        await pushLock.flush();
+        if (disposed)
+            return;
+        if (!(await pushLock.lock())) {
+            await pushLock.flush();
+            return;
+        }
+        try {
+            if (!disposed)
+                await pushAll();
+        }
+        catch (err) {
+            logger?.warn('credential-pusher', 'credential sync failed', errorMessage(err));
+        }
+        finally {
+            pushLock.unlock();
+        }
+    };
+    const watchKeys = [...OAUTH_KEY_SPECS.map((s) => s.credentialKey), ...PLAIN_KEYS];
+    for (const key of watchKeys) {
+        const stream = engine.configWatch({ key: scopedKey(undefined, key) });
+        watches.push(stream);
+        (async () => {
+            for await (const _ of stream)
+                schedule();
+            if (disposed)
+                return;
+            logger?.warn('credential-pusher', `credential watch ended for ${key}, change propagation degrades to the interval until restart`);
+        })().catch((err) => {
+            if (disposed)
+                return;
+            logger?.warn('credential-pusher', `credential watch ended for ${key}`, errorMessage(err));
+        });
+    }
+    schedule();
+    const stop = async () => {
+        if (disposed)
+            return;
+        disposed = true;
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        for (const stream of watches) {
+            try {
+                stream.destroy();
+            }
+            catch { }
+        }
+        pushLock.destroy();
+        await pushLock.flush();
+    };
+    return Object.assign(stop, { sync });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist-lib/lib/custom-model-pusher.d.ts

@@ -0,0 +1,9 @@
+import type { Harness } from './assistant.ts';
+import type { openLocalStore } from './core/local/index.ts';
+type LocalStore = Awaited<ReturnType<typeof openLocalStore>>;
+type Logger = {
+    warn(...args: unknown[]): void;
+};
+export type CustomModelTarget = Pick<Harness, 'setCustomModels'>;
+export declare function startCustomModelPusher(harness: CustomModelTarget, state: LocalStore, logger?: Logger | null): () => Promise<void>;
+export {};

package/dist-lib/lib/custom-model-pusher.js

@@ -0,0 +1,42 @@
+export function startCustomModelPusher(harness, state, logger) {
+    let disposed = false;
+    let tail = Promise.resolve();
+    let queued = false;
+    const push = async () => {
+        const rows = await state.getCustomModelRows();
+        if (disposed)
+            return;
+        await harness.setCustomModels?.(rows.map((row) => ({
+            name: row.name,
+            src: row.src,
+            projectionSrc: row.mmprojSrc ?? undefined
+        })));
+    };
+    const schedule = () => {
+        if (disposed || queued)
+            return;
+        queued = true;
+        tail = tail.then(async () => {
+            queued = false;
+            if (disposed)
+                return;
+            try {
+                await push();
+            }
+            catch (err) {
+                logger?.warn('custom-model-pusher', 'push failed', errorMessage(err));
+            }
+        });
+    };
+    const listener = () => schedule();
+    state.watch(listener);
+    schedule();
+    return async () => {
+        disposed = true;
+        state.unwatch(listener);
+        await tail;
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist-lib/lib/custom-model-source.d.ts

@@ -0,0 +1,15 @@
+type ProbeResponse = {
+    ok: boolean;
+    headers: {
+        get(name: string): string | null;
+    };
+};
+type ProbeFetch = (url: string, init: {
+    method: 'HEAD';
+    redirect: 'follow';
+}) => Promise<ProbeResponse>;
+export declare function normalizeModelSource(raw: string): string;
+export declare function probeModelSource(src: string, opts?: {
+    fetch?: ProbeFetch;
+}): Promise<number>;
+export {};

package/dist-lib/lib/custom-model-source.js

@@ -0,0 +1,46 @@
+import defaultFetch from '#fetch';
+export function normalizeModelSource(raw) {
+    const trimmed = raw.trim();
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        return trimmed;
+    }
+    if (url.hostname !== 'huggingface.co')
+        return trimmed;
+    const segments = url.pathname.split('/').filter(Boolean);
+    if (segments.length < 2)
+        return trimmed;
+    const [org, repo, kind, ...rest] = segments;
+    const showFile = url.searchParams.get('show_file_info');
+    if (showFile && segments.length === 2) {
+        return `https://huggingface.co/${org}/${repo}/resolve/main/${showFile}`;
+    }
+    if (kind === 'blob' && rest.length > 0) {
+        return `https://huggingface.co/${org}/${repo}/resolve/${rest.join('/')}`;
+    }
+    return trimmed;
+}
+export async function probeModelSource(src, opts = {}) {
+    if (!/^https?:/.test(src))
+        return 0;
+    const fetchImpl = opts.fetch ?? defaultFetch;
+    let response;
+    try {
+        response = await fetchImpl(src, { method: 'HEAD', redirect: 'follow' });
+    }
+    catch {
+        return 0;
+    }
+    const contentType = response.headers.get('content-type') ?? '';
+    if (response.ok && contentType.includes('text/html')) {
+        throw new Error('The model source URL returned a web page, not a model file. On Hugging Face use the file download link (…/resolve/…), not the repo page.');
+    }
+    const linkedSize = Number(response.headers.get('x-linked-size'));
+    if (Number.isFinite(linkedSize) && linkedSize > 0)
+        return linkedSize;
+    const contentLength = Number(response.headers.get('content-length'));
+    return Number.isFinite(contentLength) && contentLength > 0 ? contentLength : 0;
+}

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

@@ -0,0 +1,9 @@
+export declare class DeadlineScheduler {
+    private readonly _onFire;
+    private _timer;
+    private _at;
+    constructor(onFire: () => void);
+    get at(): number | null;
+    schedule(deadline: number): void;
+    clear(): void;
+}

package/dist-lib/lib/deadline.js

@@ -0,0 +1,31 @@
+import { unref } from "./unref.js";
+export class DeadlineScheduler {
+    _onFire;
+    _timer = null;
+    _at = null;
+    constructor(onFire) {
+        this._onFire = onFire;
+    }
+    get at() {
+        return this._at;
+    }
+    schedule(deadline) {
+        const at = deadline + 1;
+        if (this._at !== null && this._at <= at)
+            return;
+        this.clear();
+        this._at = at;
+        this._timer = setTimeout(() => {
+            this._timer = null;
+            this._at = null;
+            this._onFire();
+        }, Math.max(0, at - Date.now()));
+        unref(this._timer);
+    }
+    clear() {
+        if (this._timer)
+            clearTimeout(this._timer);
+        this._timer = null;
+        this._at = null;
+    }
+}

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

@@ -0,0 +1,35 @@
+import type { MemoryBudget } from '@qvac/harness';
+export interface HarnessDiagnostics {
+    models: Array<{
+        model: string;
+        refs: number;
+    }>;
+    suspended: boolean;
+    sdkLoaded: boolean;
+    toolNames: string[];
+    skills: string[];
+    device?: 'cpu' | 'gpu';
+}
+export interface RunSummary {
+    runId: string;
+    chatId: string;
+    model: string;
+}
+export interface AssistantDiagnostics {
+    suspended: boolean;
+    runs: RunSummary[];
+    activeChats: number;
+    queued: number;
+}
+export interface DiagnosticsSlice {
+    harness: HarnessDiagnostics | null;
+    assistant: AssistantDiagnostics;
+    platform: string;
+    mobileClass: boolean;
+    memoryBudget: MemoryBudget | null;
+}
+export declare function summarizeRuns(runs: Iterable<{
+    runId: string;
+    chatId: string;
+    model: string;
+}>, suspended: boolean): AssistantDiagnostics;

package/dist-lib/lib/diagnostics.js

@@ -0,0 +1,14 @@
+export function summarizeRuns(runs, suspended) {
+    const list = [];
+    const chats = new Set();
+    for (const { runId, chatId, model } of runs) {
+        list.push({ runId, chatId, model });
+        chats.add(chatId);
+    }
+    return {
+        suspended,
+        runs: list,
+        activeChats: chats.size,
+        queued: list.length - chats.size
+    };
+}

package/dist-lib/lib/fetch-node.d.ts

@@ -0,0 +1 @@
+export default fetch;

package/dist-lib/lib/fetch-node.js

@@ -0,0 +1 @@
+export default fetch;

package/dist-lib/lib/fs-drive-bridge.d.ts

@@ -0,0 +1,12 @@
+import { type DriveOpFn, type GrantedDrive } from '@qvac/harness/lib/tools/fs/remote.ts';
+import type { AcquiredDrive, DriveHost } from './core/fs-drives.ts';
+import type { FsGrant } from './fs-grants.ts';
+export declare const DRIVE_OP_TIMEOUT_MS = 15000;
+export declare function sweepDriveStaging(now?: number): Promise<void>;
+export declare function createDriveOp(drives: ReadonlyMap<string, AcquiredDrive>): DriveOpFn;
+export interface ResolvedFsGrants {
+    readonly grantedDirs: string[];
+    readonly grantedDrives: GrantedDrive[];
+    readonly driveOp?: DriveOpFn;
+}
+export declare function resolveFsGrants(grants: readonly FsGrant[], driveHost: DriveHost | undefined, onDropped?: (key: string, err: unknown) => void): Promise<ResolvedFsGrants>;