@qvac/harness 0.2.10 → 0.3.0

package/dist-lib/lib/models/model-pool.d.ts

@@ -69,6 +69,12 @@ export interface LoadedModel {
 type PoolLike = ReturnType<typeof createModelPool>;
 export declare function releaseModel(pool: PoolLike, key: string): void;
 export declare function loadedModels(pool: PoolLike): LoadedModel[];
+export interface ResidentLease {
+    model: string;
+    modelId: string;
+    release: () => void;
+}
+export declare function leaseResidentModel(pool: PoolLike, wanted?: (model: string) => boolean): Promise<ResidentLease | null>;
 export declare function isResident(pool: PoolLike, key: string): boolean;
 export declare function leaseCount(pool: PoolLike, key: string): number;
 export declare function evictIdle(pool: PoolLike): Promise<void>;

package/dist-lib/lib/models/model-pool.js

@@ -91,6 +91,18 @@ export function loadedModels(pool) {
     }
     return out;
 }
+export async function leaseResidentModel(pool, wanted = () => true) {
+    for (const entry of pool.resources.values()) {
+        const key = entry.id;
+        const pending = entry.value.peek();
+        if (!pending || entry.value.loading || !wanted(key.split('\0')[0]))
+            continue;
+        pool.open(key);
+        const loaded = await pending;
+        return { model: loaded.model, modelId: loaded.modelId, release: () => releaseModel(pool, key) };
+    }
+    return null;
+}
 export function isResident(pool, key) {
     const handle = entryOf(pool, key)?.value;
     return handle !== undefined && handle.peek() !== null;

package/dist-lib/lib/models/nmt-catalog.d.ts

@@ -0,0 +1,34 @@
+export declare const ENGLISH = "en";
+export declare const NMT_TO_ENGLISH: readonly string[];
+export declare const NMT_FROM_ENGLISH: readonly string[];
+export declare const SLM_MODEL = "TranslatePsy-AfriSLM-0.8B-Q4_K_M-imat";
+export declare function isTranslationModel(model: string): boolean;
+export declare const EURONANO_LANGUAGES: readonly string[];
+export declare const SLM_LANGUAGE_CODES: readonly string[];
+export declare function languageLabel(code: string): string | undefined;
+export declare const SLM_LANGUAGE_NAMES: ReadonlyArray<{
+    code: string;
+    name: string;
+}>;
+export declare function slmLanguage(code: string): string | undefined;
+export interface NmtPlan {
+    route: 'nmt';
+    from: string;
+    to: string;
+    model: string;
+    pivot?: string;
+    srcVocab?: string;
+    dstVocab?: string;
+    tag?: string;
+}
+export interface SlmPlan {
+    route: 'slm';
+    from: string;
+    to: string;
+    model: string;
+}
+export type TranslationPlan = NmtPlan | SlmPlan;
+export declare function sameLanguage(from: string, to: string): boolean;
+export declare function translationPlanFor(requestedFrom: string, requestedTo: string): TranslationPlan | {
+    error: string;
+};

package/dist-lib/lib/models/nmt-catalog.js

@@ -0,0 +1,166 @@
+export const ENGLISH = 'en';
+const TO_ENGLISH = [
+    'ar',
+    'az',
+    'be',
+    'bg',
+    'bn',
+    'bs',
+    'ca',
+    'cs',
+    'da',
+    'de',
+    'el',
+    'es',
+    'et',
+    'fa',
+    'fi',
+    'fr',
+    'gu',
+    'he',
+    'hi',
+    'hr',
+    'hu',
+    'id',
+    'is',
+    'it',
+    'ja',
+    'kn',
+    'ko',
+    'lt',
+    'lv',
+    'ml',
+    'ms',
+    'mt',
+    'nb',
+    'nl',
+    'nn',
+    'no',
+    'pl',
+    'pt',
+    'ro',
+    'ru',
+    'sk',
+    'sl',
+    'sq',
+    'sr',
+    'sv',
+    'ta',
+    'te',
+    'th',
+    'tr',
+    'uk',
+    'vi',
+    'zh'
+];
+const FROM_ENGLISH = TO_ENGLISH.filter((code) => !['be', 'mt', 'nn'].includes(code));
+export const NMT_TO_ENGLISH = TO_ENGLISH;
+export const NMT_FROM_ENGLISH = FROM_ENGLISH;
+const SLM_LANGUAGES = [
+    { iso: 'af', flores: 'afr_Latn', name: 'Afrikaans' },
+    { iso: 'am', flores: 'amh_Ethi', name: 'Amharic' },
+    { iso: 'ha', flores: 'hau_Latn', name: 'Hausa' },
+    { iso: 'ig', flores: 'ibo_Latn', name: 'Igbo' },
+    { iso: 'rw', flores: 'kin_Latn', name: 'Kinyarwanda' },
+    { iso: 'mg', flores: 'plt_Latn', name: 'Malagasy' },
+    { iso: 'ny', flores: 'nya_Latn', name: 'Nyanja' },
+    { iso: 'om', flores: 'gaz_Latn', name: 'Oromo' },
+    { iso: 'sn', flores: 'sna_Latn', name: 'Shona' },
+    { iso: 'so', flores: 'som_Latn', name: 'Somali' },
+    { iso: 'st', flores: 'sot_Latn', name: 'Southern Sotho' },
+    { iso: 'sw', flores: 'swh_Latn', name: 'Swahili' },
+    { iso: 'tn', flores: 'tsn_Latn', name: 'Tswana' },
+    { iso: 'xh', flores: 'xho_Latn', name: 'Xhosa' },
+    { iso: 'yo', flores: 'yor_Latn', name: 'Yoruba' },
+    { iso: 'zu', flores: 'zul_Latn', name: 'Zulu' }
+];
+export const SLM_MODEL = 'TranslatePsy-AfriSLM-0.8B-Q4_K_M-imat';
+export function isTranslationModel(model) {
+    return /(^|[/\\])TranslatePsy-/.test(model);
+}
+const EURONANO = 'https://huggingface.co/qvac/TranslatePsy-EuroNano/resolve/main';
+const EURONANO_SIZE = 'Base';
+export const EURONANO_LANGUAGES = [
+    'cs',
+    'de',
+    'es',
+    'fi',
+    'fr',
+    'it',
+    'nl',
+    'pt',
+    'sv'
+];
+function euroNanoPack(direction) {
+    const dir = `${EURONANO}/${direction}/${EURONANO_SIZE}/intgemm`;
+    return { model: `${dir}/model.intgemm.alphas.bin`, vocab: `${dir}/vocab.spm` };
+}
+export const SLM_LANGUAGE_CODES = SLM_LANGUAGES.map((entry) => entry.iso);
+export function languageLabel(code) {
+    const wanted = code.toLowerCase();
+    return SLM_LANGUAGES.find((entry) => entry.flores.toLowerCase() === wanted || entry.iso === wanted)?.name;
+}
+export const SLM_LANGUAGE_NAMES = SLM_LANGUAGES.map(({ iso, name }) => ({ code: iso, name }));
+export function slmLanguage(code) {
+    const wanted = code.toLowerCase();
+    return SLM_LANGUAGES.find((entry) => entry.flores.toLowerCase() === wanted || entry.iso === wanted)?.flores;
+}
+const modelFilter = (pair) => `model.${pair}.intgemm`;
+export function sameLanguage(from, to) {
+    return canonical(from) === canonical(to);
+}
+function canonical(code) {
+    return slmLanguage(code) ?? code.toLowerCase();
+}
+export function translationPlanFor(requestedFrom, requestedTo) {
+    const from = requestedFrom.toLowerCase();
+    const to = requestedTo.toLowerCase();
+    if (sameLanguage(from, to))
+        return { error: `${from} is already the target language` };
+    const slmFrom = slmLanguage(from);
+    const slmTo = slmLanguage(to);
+    if (slmFrom || slmTo) {
+        return { route: 'slm', from: slmFrom ?? from, to: slmTo ?? to, model: SLM_MODEL };
+    }
+    if (to === ENGLISH && EURONANO_LANGUAGES.includes(from)) {
+        const pack = euroNanoPack('xx-en');
+        return {
+            route: 'nmt',
+            from,
+            to,
+            model: pack.model,
+            srcVocab: pack.vocab,
+            dstVocab: pack.vocab
+        };
+    }
+    if (from === ENGLISH && EURONANO_LANGUAGES.includes(to)) {
+        const pack = euroNanoPack('en-xx');
+        return {
+            route: 'nmt',
+            from,
+            to,
+            model: pack.model,
+            srcVocab: pack.vocab,
+            dstVocab: pack.vocab,
+            tag: `##${to.toUpperCase()}`
+        };
+    }
+    if (to === ENGLISH) {
+        if (!TO_ENGLISH.includes(from))
+            return { error: `cannot translate from ${from}` };
+        return { route: 'nmt', from, to, model: modelFilter(`${from}${ENGLISH}`) };
+    }
+    if (!FROM_ENGLISH.includes(to))
+        return { error: `cannot translate to ${to}` };
+    if (from === ENGLISH)
+        return { route: 'nmt', from, to, model: modelFilter(`${ENGLISH}${to}`) };
+    if (!TO_ENGLISH.includes(from))
+        return { error: `cannot translate from ${from}` };
+    return {
+        route: 'nmt',
+        from,
+        to,
+        model: modelFilter(`${from}${ENGLISH}`),
+        pivot: modelFilter(`${ENGLISH}${to}`)
+    };
+}

package/dist-lib/lib/serve.js

@@ -4,6 +4,7 @@ import { settleOnClose } from './rpc-session.js';
 import { pipeline, Readable } from 'streamx';
 import { bindApi } from '../spec/bind.js';
 import HRPC from '../spec/hrpc/index.js';
+import { isCapability } from './capabilities/invoke.js';
 import { unsupportedKvCacheDeletion } from './capabilities/kv-cache.js';
 import { errorMessage } from './error-fields.js';
 import { hlog } from './log.js';
@@ -11,7 +12,7 @@ import { pushQueue } from './queue.js';
 import { TextCoalescer } from './helpers/text-coalescer.js';
 import { prepareOpenclCache } from './models/opencl-cache.js';
 import { stageFile, sweepStaging } from './staging.js';
-import { readSetup } from './tools/skills/manifest-parse.js';
+import { readSetup, toWireSetup } from './tools/skills/manifest-parse.js';
 import { packVectors, toDownloadWire, toWire } from './wire.js';
 const MODEL_STATUSES = new Set([
     'loading',
@@ -96,6 +97,15 @@ export function serveHarness(stream, harness) {
                 text: await harness.transcribe({ model: model ?? '', audio: audio ?? Buffer.alloc(0) })
             };
         },
+        detectLanguage: async ({ text, topK }) => {
+            if (!harness.detectLanguage)
+                throw new Error('harness does not support detectLanguage');
+            const languages = await harness.detectLanguage({
+                text: text ?? '',
+                topK: topK ?? undefined
+            });
+            return { languages };
+        },
         speak: async ({ model, text }) => {
             if (!harness.speak)
                 throw new Error('harness does not support speak');
@@ -159,7 +169,7 @@ export function serveHarness(stream, harness) {
     });
 }
 function toWireSkill(skill) {
-    const setupV2 = readSetup(skill.setup);
+    const setupV2 = toWireSetup(readSetup(skill.setup));
     const binaries = (skill.requires?.bins ?? []).map((bin) => ({
         bin,
         minVersion: skill.requires?.binMinVersions?.[bin]?.min,
@@ -275,6 +285,25 @@ function speakStream(harness) {
         }
     };
 }
+function runFrame(harness, frame, context) {
+    if (frame.type !== 'invoke')
+        return harness.completion(context);
+    if (!harness.invoke)
+        throw new Error('harness does not support invoke');
+    const capability = frame.capability ?? '';
+    if (!isCapability(capability))
+        throw new Error(`unknown capability: ${capability}`);
+    return harness.invoke({
+        capability,
+        args: frame.arguments ?? {},
+        enhance: frame.enhance === 'auto' ? 'auto' : 'never',
+        agent: frame.agent ?? undefined,
+        attach: context.attach,
+        fetchAttachment: context.fetchAttachment,
+        progress: context.progress,
+        signal: context.signal
+    });
+}
 function completion(harness) {
     return async function* (duplex) {
         const events = pushQueue({ highWaterMark: WIRE_HIGH_WATER_MARK });
@@ -404,7 +433,7 @@ function completion(harness) {
                 waiter.resolve((frame.payload ?? {}));
                 return;
             }
-            if (frame.type !== 'start' || started)
+            if (started || (frame.type !== 'start' && frame.type !== 'invoke'))
                 return;
             started = true;
             const context = {
@@ -523,7 +552,7 @@ function completion(harness) {
                     return events.push({ type, text: merged });
                 }, { cap: TEXT_COALESCE_CAP, holdMs: TEXT_COALESCE_MS });
                 try {
-                    for await (const event of harness.completion(context)) {
+                    for await (const event of runFrame(harness, frame, context)) {
                         produced++;
                         const wire = toWire(event);
                         if ((wire.type === 'content' || wire.type === 'thinking') && wire.text) {

package/dist-lib/lib/tools/generate-image.js

@@ -1,6 +1,7 @@
 import ScopeLock from 'scope-lock';
 import { AbortedError, raceAbort } from '../helpers/race-abort.js';
 import { DIFFUSION_CATALOG, imageModelFor } from '../models/model-catalog.js';
+import { createLoadStall } from '../helpers/load-stall.js';
 import { createLoadTracker } from '../models/model-pool.js';
 import { resolveModelSrc } from '../models/model-source.js';
 export const MAX_DIM = 1024;
@@ -36,30 +37,6 @@ function diffusionProgressName(set) {
     return entry?.name ?? set.model;
 }
 export const IMAGE_LOAD_STALL_ERROR = 'image model download stalled';
-function createLoadStall(ms) {
-    let timer = null;
-    let rejectStall = null;
-    const promise = new Promise((_, reject) => {
-        rejectStall = reject;
-    });
-    const arm = () => {
-        if (timer !== null)
-            clearTimeout(timer);
-        timer = setTimeout(() => {
-            rejectStall?.(new Error(IMAGE_LOAD_STALL_ERROR));
-        }, ms);
-    };
-    arm();
-    return {
-        bump: arm,
-        clear: () => {
-            if (timer !== null)
-                clearTimeout(timer);
-            timer = null;
-        },
-        promise
-    };
-}
 export function createDiffusionRuntime({ loadSdk, onProgress, onLoaded, onBeforeLoad, loads = createLoadTracker(), stallMs = IMAGE_LOAD_STALL_MS, ...base }) {
     let loading = null;
     let residentFingerprint = null;
@@ -116,7 +93,7 @@ export function createDiffusionRuntime({ loadSdk, onProgress, onLoaded, onBefore
                         config.vaeModelSrc = await resolveModelSrc(sdk, set.vaeModel, 'diffusion');
                     }
                     const modelConfig = Object.keys(config).length ? config : undefined;
-                    const stall = createLoadStall(stallMs);
+                    const stall = createLoadStall(stallMs, IMAGE_LOAD_STALL_ERROR);
                     const pending = sdk.loadModel({
                         modelSrc,
                         modelType: 'diffusion',

package/dist-lib/lib/tools/http-request.js

@@ -14,7 +14,7 @@ export function createHttpRequestTool({ fetch: fetchImpl, credentialStore, crede
     return {
         name: 'http_request',
         toolset: 'http-request',
-        description: 'Make an outbound HTTP or HTTPS request and return the response status and body (truncated). Authorization/Cookie headers are stripped before sending. Stored skill credentials are attached automatically for their allow-listed hosts; `auth` is only needed to force a specific credential key.',
+        description: 'Make an outbound HTTP or HTTPS request and return the response status and body (truncated) as text. Authorization/Cookie headers are stripped before sending. Stored skill credentials are attached automatically for their allow-listed hosts; `auth` is only needed to force a specific credential key. For APIs and text responses only: a URL that serves a file — PDF, .docx, .xlsx, an image, any binary — comes back as truncated garbage here. Use web_fetch for those; it downloads and attaches the file.',
         parameters: {
             type: 'object',
             properties: {

package/dist-lib/lib/tools/skills/manifest-parse.d.ts

@@ -10,3 +10,4 @@ export interface ParsedManifest {
 export declare function parseManifestBlock(block: string, key?: string): ParsedManifest;
 export declare function readInstall(v: unknown): InstallStep[] | undefined;
 export declare function readSetup(v: unknown): SkillSetup | undefined;
+export declare function toWireSetup(setup: SkillSetup | undefined): unknown;

package/dist-lib/lib/tools/skills/manifest-parse.js

@@ -165,6 +165,9 @@ function readRoutes(v) {
         const steps = strArr(raw.steps);
         const configSteps = strArr(raw.configSteps);
         const fields = readFields(raw.fields);
+        const oauth = readOAuth(raw.oauth);
+        if (raw.kind === 'oauth' && !oauth)
+            continue;
         routes.push({
             kind: raw.kind,
             label: raw.label,
@@ -175,11 +178,99 @@ function readRoutes(v) {
             ...(steps ? { steps } : {}),
             ...(configSteps ? { configSteps } : {}),
             ...(fields ? { fields } : {}),
-            ...(typeof raw.satisfied === 'boolean' ? { satisfied: raw.satisfied } : {})
+            ...(typeof raw.satisfied === 'boolean' ? { satisfied: raw.satisfied } : {}),
+            ...(oauth ? { oauth } : {})
         });
     }
     return routes.length > 0 ? routes : undefined;
 }
+const OAUTH_TOKEN_AUTH = new Set(['pkce-only', 'secret-in-body', 'secret-in-basic']);
+const OAUTH_RESERVED_PARAMS = new Set([
+    'client_id',
+    'client_secret',
+    'redirect_uri',
+    'response_type',
+    'state',
+    'scope',
+    'code_challenge',
+    'code_challenge_method'
+]);
+function isOAuthTokenAuth(v) {
+    return typeof v === 'string' && OAUTH_TOKEN_AUTH.has(v);
+}
+function httpsUrl(v) {
+    if (typeof v !== 'string' || v.length === 0)
+        return undefined;
+    try {
+        return new URL(v).protocol === 'https:' ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPort(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v > 0 && v < 65536;
+}
+function readAuthParams(v) {
+    const raw = Array.isArray(v)
+        ? Object.fromEntries(v.flatMap((pair) => isObj(pair) && typeof pair.key === 'string' && typeof pair.value === 'string'
+            ? [[pair.key, pair.value]]
+            : []))
+        : v;
+    const record = readStringRecord(raw);
+    if (!record)
+        return undefined;
+    const out = Object.fromEntries(Object.entries(record).filter(([key]) => !OAUTH_RESERVED_PARAMS.has(key)));
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function readOAuth(v) {
+    if (!isObj(v))
+        return undefined;
+    const authUrl = httpsUrl(v.authUrl);
+    const tokenUrl = httpsUrl(v.tokenUrl);
+    if (typeof v.stateKey !== 'string' ||
+        v.stateKey.length === 0 ||
+        !authUrl ||
+        !tokenUrl ||
+        !isOAuthTokenAuth(v.tokenAuth)) {
+        return undefined;
+    }
+    const scopes = v.scopes === undefined || v.scopes === null ? [] : strArr(v.scopes);
+    if (!scopes)
+        return undefined;
+    const extraAuthParams = readAuthParams(v.extraAuthParams);
+    const registrationEndpoint = httpsUrl(v.registrationEndpoint);
+    return {
+        stateKey: v.stateKey,
+        authUrl,
+        tokenUrl,
+        scopes,
+        tokenAuth: v.tokenAuth,
+        ...(extraAuthParams ? { extraAuthParams } : {}),
+        ...(registrationEndpoint ? { registrationEndpoint } : {}),
+        ...(isPort(v.port) ? { port: v.port } : {}),
+        ...(typeof v.sharedIosSession === 'boolean' ? { sharedIosSession: v.sharedIosSession } : {})
+    };
+}
+export function toWireSetup(setup) {
+    if (!setup?.routes)
+        return setup;
+    return {
+        ...setup,
+        routes: setup.routes.map((route) => route.oauth?.extraAuthParams
+            ? {
+                ...route,
+                oauth: {
+                    ...route.oauth,
+                    extraAuthParams: Object.entries(route.oauth.extraAuthParams).map(([key, value]) => ({
+                        key,
+                        value
+                    }))
+                }
+            }
+            : route)
+    };
+}
 function readFields(v) {
     if (!Array.isArray(v))
         return undefined;

package/dist-lib/lib/tools/skills/manifest.d.ts

@@ -29,6 +29,17 @@ export interface SkillSetupField {
     readonly secret?: boolean;
     readonly required?: boolean;
 }
+export interface SkillOAuthConfig {
+    readonly stateKey: string;
+    readonly authUrl: string;
+    readonly tokenUrl: string;
+    readonly scopes: readonly string[];
+    readonly tokenAuth: 'pkce-only' | 'secret-in-body' | 'secret-in-basic';
+    readonly extraAuthParams?: Readonly<Record<string, string>>;
+    readonly registrationEndpoint?: string;
+    readonly port?: number;
+    readonly sharedIosSession?: boolean;
+}
 export interface SkillSetupRoute {
     readonly kind: 'oauth' | 'token' | 'install' | 'picker' | 'instructions';
     readonly label: string;
@@ -40,6 +51,7 @@ export interface SkillSetupRoute {
     readonly configSteps?: readonly string[];
     readonly fields?: readonly SkillSetupField[];
     readonly satisfied?: boolean;
+    readonly oauth?: SkillOAuthConfig;
 }
 export interface SkillSetup {
     readonly summary?: string;

package/dist-lib/lib/tools/translate.d.ts

@@ -0,0 +1,78 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { ToolDefinition } from '../capabilities/completion.ts';
+import type { ModelSrc } from '../models/context.ts';
+import { type NmtPlan } from '../models/nmt-catalog.ts';
+import { type LoadTracker, type TrackedLoad } from '../models/model-pool.ts';
+import { type ModelRegistrySdk } from '../models/model-source.ts';
+interface BergamotConfig {
+    engine: 'Bergamot';
+    from: string;
+    to: string;
+    pivotModel?: {
+        modelSrc: ModelSrc;
+    };
+    srcVocabSrc?: string;
+    dstVocabSrc?: string;
+}
+export type TranslationSdk = ModelRegistrySdk & {
+    loadModel(params: {
+        modelSrc: ModelSrc;
+        modelType: 'nmtcpp-translation';
+        modelConfig: BergamotConfig;
+        onProgress?: (progress: Record<string, unknown>) => void;
+    }): TrackedLoad;
+    unloadModel(params: {
+        modelId: string;
+    }): Promise<unknown>;
+    cancel?(params: {
+        requestId: string;
+    }): Promise<void>;
+    translate(params: {
+        modelId: string;
+        text: string;
+        stream: false;
+        modelType: 'nmt';
+    }): {
+        text: Promise<string>;
+    };
+};
+export declare const TRANSLATION_LOAD_STALL_MS: number;
+export declare const TRANSLATION_LOAD_STALL_ERROR = "translation model download stalled";
+export interface TranslationRuntimeOptions {
+    loadSdk: () => Promise<TranslationSdk>;
+    loads?: LoadTracker;
+    onProgress?: (model: string, progress: Record<string, unknown>) => void;
+    stallMs?: number;
+}
+export interface TranslationRuntime {
+    loadSdk: () => Promise<TranslationSdk>;
+    ensureLoaded: (sdk: TranslationSdk, plan: NmtPlan, signal?: BareAbortSignal) => Promise<{
+        modelId: string;
+    }>;
+    unload: () => Promise<void>;
+    enter: (signal?: BareAbortSignal) => Promise<void>;
+    exit: () => void;
+}
+export declare function createTranslationRuntime({ loadSdk, loads, onProgress, stallMs }: TranslationRuntimeOptions): TranslationRuntime;
+export type SlmTranslateFn = (model: string, params: {
+    text: string;
+    from: string;
+    to: string;
+}, signal?: BareAbortSignal) => Promise<string>;
+export declare function stripLanguageLabel(text: string, ...codes: string[]): string;
+export interface TranslateArgs {
+    text: string;
+    to: string;
+    from?: string;
+}
+export declare function parseTranslateArgs(args: Record<string, unknown>): TranslateArgs | {
+    error: string;
+};
+export declare function sourceLanguage(text: string, from?: string): string | {
+    error: string;
+};
+export interface TranslateToolOptions {
+    slm?: SlmTranslateFn;
+}
+export declare function createTranslateTool(runtime: TranslationRuntime, { slm }?: TranslateToolOptions): ToolDefinition;
+export {};