@qvac/harness 0.1.0 → 0.1.1

package/dist-lib/lib/audio-transcode-bare.d.ts

@@ -0,0 +1,2 @@
+export declare function transcodeToWav16kMono(input: Buffer): Promise<Buffer | null>;
+export declare function transcodeToPcm16kMono(input: Buffer): Promise<Buffer | null>;

package/dist-lib/lib/audio-transcode-bare.js

@@ -0,0 +1,145 @@
+import ffmpeg from 'bare-ffmpeg';
+import { hlog } from "./log.js";
+import { buildWavBuffer, TARGET_SAMPLE_RATE } from "./wav-encode.js";
+function bufferReadIO(input) {
+    let offset = 0;
+    return new ffmpeg.IOContext(Buffer.alloc(4096), {
+        onread: (buffer, requested) => {
+            const remaining = input.length - offset;
+            if (remaining <= 0)
+                return 0;
+            const n = Math.min(requested, remaining);
+            buffer.set(input.subarray(offset, offset + n));
+            offset += n;
+            return n;
+        },
+        onseek: (o, whence) => {
+            if (whence === ffmpeg.constants.seek.SIZE)
+                return input.length;
+            if (whence === ffmpeg.constants.seek.SET) {
+                offset = o;
+            }
+            else if (whence === ffmpeg.constants.seek.CUR) {
+                offset += o;
+            }
+            else if (whence === ffmpeg.constants.seek.END) {
+                offset = input.length + o;
+            }
+            else {
+                return -1;
+            }
+            return offset;
+        }
+    });
+}
+function makeOutFrame(capacity) {
+    const out = new ffmpeg.Frame();
+    out.format = ffmpeg.constants.sampleFormats.S16;
+    out.channelLayout = ffmpeg.constants.channelLayouts.MONO;
+    out.sampleRate = TARGET_SAMPLE_RATE;
+    out.nbSamples = capacity;
+    out.alloc();
+    return out;
+}
+function readChunk(samples, outFrame, produced) {
+    if (produced <= 0)
+        return null;
+    samples.read(outFrame);
+    return Buffer.from(samples.data.subarray(0, produced * 2));
+}
+function createResampler(frame) {
+    return new ffmpeg.Resampler(frame.sampleRate, frame.channelLayout, frame.format, TARGET_SAMPLE_RATE, ffmpeg.constants.channelLayouts.MONO, ffmpeg.constants.sampleFormats.S16);
+}
+function convertFrame(resampler, frame, samples) {
+    const capacity = Math.ceil((frame.nbSamples * TARGET_SAMPLE_RATE) / frame.sampleRate) + 1024;
+    const outFrame = makeOutFrame(capacity);
+    const chunk = readChunk(samples, outFrame, resampler.convert(frame, outFrame));
+    outFrame.destroy();
+    return chunk;
+}
+function flushResampler(resampler, samples) {
+    if (!resampler)
+        return [];
+    const chunks = [];
+    let flushed = 0;
+    do {
+        const outFrame = makeOutFrame(TARGET_SAMPLE_RATE);
+        flushed = resampler.flush(outFrame);
+        const chunk = readChunk(samples, outFrame, flushed);
+        if (chunk)
+            chunks.push(chunk);
+        outFrame.destroy();
+    } while (flushed > 0);
+    return chunks;
+}
+function drainDecodedFrames(decoder, frame, samples, resampler, chunks) {
+    let current = resampler;
+    while (decoder.receiveFrame(frame)) {
+        current ??= createResampler(frame);
+        const chunk = convertFrame(current, frame, samples);
+        if (chunk)
+            chunks.push(chunk);
+    }
+    return current;
+}
+const YIELD_EVERY_PACKETS = 32;
+function yieldToLoop() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+async function decodeToPcmChunks(inputFormat, stream, decoder) {
+    const chunks = [];
+    const packet = new ffmpeg.Packet();
+    const flush = new ffmpeg.Packet();
+    const frame = new ffmpeg.Frame();
+    const samples = new ffmpeg.Samples();
+    let resampler = null;
+    let packets = 0;
+    try {
+        while (inputFormat.readFrame(packet)) {
+            if (packet.streamIndex === stream.index && decoder.sendPacket(packet)) {
+                resampler = drainDecodedFrames(decoder, frame, samples, resampler, chunks);
+            }
+            packet.unref();
+            if (++packets % YIELD_EVERY_PACKETS === 0)
+                await yieldToLoop();
+        }
+        decoder.sendPacket(flush);
+        resampler = drainDecodedFrames(decoder, frame, samples, resampler, chunks);
+        chunks.push(...flushResampler(resampler, samples));
+    }
+    finally {
+        resampler?.destroy();
+        frame.destroy();
+        flush.destroy();
+        packet.destroy();
+    }
+    return chunks;
+}
+async function decodeInputToPcm(input) {
+    let inputFormat = null;
+    let decoder = null;
+    try {
+        inputFormat = new ffmpeg.InputFormatContext(bufferReadIO(input));
+        const stream = inputFormat.getBestStream(ffmpeg.constants.mediaTypes.AUDIO);
+        decoder = stream.decoder();
+        decoder.open();
+        const chunks = await decodeToPcmChunks(inputFormat, stream, decoder);
+        return chunks.length === 0 ? null : Buffer.concat(chunks);
+    }
+    catch (e) {
+        hlog('audio decode/resample failed', { error: e instanceof Error ? e.message : String(e) });
+        return null;
+    }
+    finally {
+        if (decoder)
+            decoder.destroy();
+        inputFormat?.destroy();
+    }
+}
+export async function transcodeToWav16kMono(input) {
+    const pcm = await decodeInputToPcm(input);
+    return pcm ? buildWavBuffer(pcm) : null;
+}
+export async function transcodeToPcm16kMono(input) {
+    return decodeInputToPcm(input);
+}

package/dist-lib/lib/audio-transcode-node.d.ts

@@ -0,0 +1,2 @@
+export declare function transcodeToWav16kMono(_input: Buffer): Promise<Buffer | null>;
+export declare function transcodeToPcm16kMono(_input: Buffer): Promise<Buffer | null>;

package/dist-lib/lib/audio-transcode-node.js

@@ -0,0 +1,6 @@
+export async function transcodeToWav16kMono(_input) {
+    return null;
+}
+export async function transcodeToPcm16kMono(_input) {
+    return null;
+}

package/dist-lib/lib/capabilities/audio-resample.d.ts

@@ -0,0 +1,14 @@
+interface WavFormat {
+    readonly formatCode: number;
+    readonly channels: number;
+    readonly sampleRate: number;
+    readonly bitsPerSample: number;
+}
+export declare function wavFormat(bytes: Buffer): WavFormat | null;
+export declare function needsResample(bytes: Buffer): boolean;
+export declare function resampleForTranscription(bytes: Buffer): Promise<{
+    readonly bytes: Buffer;
+    readonly transcoded: boolean;
+}>;
+export declare function pcmForTranscription(bytes: Buffer): Promise<Buffer | null>;
+export {};

package/dist-lib/lib/capabilities/audio-resample.js

@@ -0,0 +1,72 @@
+import { transcodeToPcm16kMono, transcodeToWav16kMono } from '#audio-transcode';
+const TARGET_SAMPLE_RATE = 16000;
+const TARGET_CHANNELS = 1;
+const TARGET_BITS_PER_SAMPLE = 16;
+const WAV_PCM_FORMAT = 1;
+export function wavFormat(bytes) {
+    if (bytes.length < 44)
+        return null;
+    if (bytes.toString('ascii', 0, 4) !== 'RIFF')
+        return null;
+    if (bytes.toString('ascii', 8, 12) !== 'WAVE')
+        return null;
+    return {
+        formatCode: bytes.readUInt16LE(20),
+        channels: bytes.readUInt16LE(22),
+        sampleRate: bytes.readUInt32LE(24),
+        bitsPerSample: bytes.readUInt16LE(34)
+    };
+}
+function wavNeedsResample(bytes) {
+    const fmt = wavFormat(bytes);
+    if (!fmt)
+        return true;
+    return (fmt.formatCode !== WAV_PCM_FORMAT ||
+        fmt.channels !== TARGET_CHANNELS ||
+        fmt.sampleRate !== TARGET_SAMPLE_RATE ||
+        fmt.bitsPerSample !== TARGET_BITS_PER_SAMPLE);
+}
+export function needsResample(bytes) {
+    if (bytes.length < 12)
+        return false;
+    if (bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WAVE') {
+        return wavNeedsResample(bytes);
+    }
+    if (bytes.toString('ascii', 4, 8) === 'ftyp')
+        return true;
+    if (bytes.toString('ascii', 0, 3) === 'ID3')
+        return true;
+    if (bytes[0] === 0xff && ((bytes[1] ?? 0) & 0xe0) === 0xe0)
+        return true;
+    if (bytes.toString('ascii', 0, 4) === 'OggS')
+        return true;
+    if (bytes.toString('ascii', 0, 4) === 'fLaC')
+        return true;
+    return false;
+}
+export async function resampleForTranscription(bytes) {
+    if (!needsResample(bytes))
+        return { bytes, transcoded: false };
+    const wav = await transcodeToWav16kMono(bytes);
+    return wav ? { bytes: wav, transcoded: true } : { bytes, transcoded: false };
+}
+function wavPcmData(bytes) {
+    let offset = 12;
+    while (offset + 8 <= bytes.length) {
+        const id = bytes.toString('ascii', offset, offset + 4);
+        const size = bytes.readUInt32LE(offset + 4);
+        const start = offset + 8;
+        if (id === 'data')
+            return bytes.subarray(start, Math.min(start + size, bytes.length));
+        offset = start + size + (size & 1);
+    }
+    return null;
+}
+export async function pcmForTranscription(bytes) {
+    if (wavFormat(bytes) && !needsResample(bytes)) {
+        const pcm = wavPcmData(bytes);
+        if (pcm)
+            return pcm;
+    }
+    return transcodeToPcm16kMono(bytes);
+}

package/dist-lib/lib/capabilities/completion.d.ts

@@ -0,0 +1,288 @@
+import type { CompletionFinal, Tool as SdkTool, ToolDialect } from '@qvac/sdk';
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import { type TextEvent } from '../helpers/thinking.ts';
+import type { ToolCallDisplay } from '../tool-call-display.ts';
+import { type LlmGenerationParams } from '../models/llm-presets.ts';
+import type { DriveRoot } from '../tools/fs/scope.ts';
+import { type UsageBreakdown } from './usage-breakdown.ts';
+import { type TrustedSource } from '../tools/outbound-guard.ts';
+import type { SkillCatalogEntry } from '../tools/skills/catalog.ts';
+import { type SkillState } from '../tools/skills/skill-state-constants.ts';
+import type { CliValidator } from '../tools/skills/cli-schema.ts';
+import { type Toolset } from '../tools/toolsets.ts';
+export interface Message {
+    role: string;
+    content: string;
+    attachments?: {
+        path: string;
+    }[];
+    [key: string]: unknown;
+}
+export interface Agent {
+    id?: string;
+    name?: string;
+    bio?: string;
+    enabledTools?: string[] | null;
+    enabledSkills?: string[] | null;
+    toolsScope?: 'all' | 'selected' | null;
+    skillsScope?: 'all' | 'selected' | null;
+    reasoning?: 'inherit' | 'enabled' | 'disabled' | null;
+    ctxSize?: number | null;
+    kvCacheK?: string | null;
+    kvCacheV?: string | null;
+    imageModelChoice?: string | null;
+    imageSteps?: number | null;
+    imageWidth?: number | null;
+    imageHeight?: number | null;
+    approvalMode?: 'ask' | 'skip-all' | null;
+    disabledToolsets?: string[] | null;
+}
+export interface ImageSettings {
+    modelChoice?: string;
+    steps?: number;
+    width?: number;
+    height?: number;
+}
+export declare function imageSettingsFrom(agent?: Agent): ImageSettings | undefined;
+export interface MusicSettings {
+    modelChoice?: string;
+    steps?: number;
+    duration?: number;
+}
+export interface ResourceDescriptor {
+    kind: string;
+    label: string;
+}
+export type ToolEffect = 'read' | 'write';
+export type ApproveFn = (call: {
+    name: string;
+    arguments: Record<string, unknown>;
+    resource?: ResourceDescriptor | null;
+    effect?: ToolEffect;
+    intent?: string | null;
+    display?: ToolCallDisplay | null;
+}) => Promise<boolean>;
+export type ToolDecision = 'auto' | 'allowed' | 'denied' | 'skip-all' | 'blocked';
+export type ToolActivityFn = (entry: ToolActivityEvent) => void;
+export interface AttachInput {
+    fileName: string;
+    mimeType: string;
+    bytes: Uint8Array;
+    raw?: boolean;
+}
+export interface AttachmentRecord {
+    id: string;
+    fileName: string;
+    mimeType: string;
+    byteLength: number;
+}
+export type AttachFn = (input: AttachInput) => Promise<AttachmentRecord>;
+export interface AttachmentMeta {
+    id: string;
+    fileName: string;
+    mimeType: string;
+    byteLength: number;
+}
+export interface FetchedAttachment extends AttachmentMeta {
+    bytes: Uint8Array;
+}
+export type FetchAttachmentFn = (query: {
+    attachmentId?: string;
+    signal?: BareAbortSignal;
+    meta?: boolean;
+}) => Promise<FetchedAttachment | AttachmentMeta | null>;
+export type ProgressFn = (update: {
+    percentage: number;
+} | null) => void;
+export type RagSearchFn = (input: {
+    query: string;
+    limit?: number;
+}) => Promise<RagSearchResult>;
+export interface RagSearchResult {
+    enabled: boolean;
+    indexEmpty: boolean;
+    hasKnowledge: boolean;
+    pendingReferenced?: boolean;
+    errorMessage?: string | null;
+    hits: ReadonlyArray<{
+        content: string;
+        metadataJson?: string | null;
+        score: number;
+    }>;
+}
+export type AskUserFn = (question: {
+    question: string;
+    options?: string[];
+}) => Promise<string | null>;
+export interface RunBudget {
+    readonly deadlineMs: number;
+    outputBytesUsed: number;
+}
+export interface ToolExecuteContext {
+    agentId?: string | null | undefined;
+    skills?: readonly string[] | undefined;
+    ctxSize?: number | undefined;
+    image?: ImageSettings | undefined;
+    settings?: Record<string, unknown> | undefined;
+    turnImages?: {
+        path: string;
+    }[] | undefined;
+    attach?: AttachFn | undefined;
+    fetchAttachment?: FetchAttachmentFn | undefined;
+    ragSearch?: RagSearchFn | undefined;
+    progress?: ProgressFn | undefined;
+    askUser?: AskUserFn | undefined;
+    signal?: BareAbortSignal | undefined;
+    fsRoots?: readonly DriveRoot[] | undefined;
+    fsWriteRoots?: readonly DriveRoot[] | undefined;
+    toolOps?: ReadonlyMap<string, readonly CliValidator[]> | undefined;
+    runBudget?: RunBudget | undefined;
+    reportBackend?: ((use: RunBackendUse) => void) | undefined;
+}
+export interface RunBackendUse {
+    tool: string;
+    requestedGpu: boolean;
+    device: 'gpu' | 'cpu' | 'unknown';
+    backend: string;
+}
+export type ToolParameterType = 'string' | 'number' | 'boolean' | 'object' | 'integer' | 'array' | 'null';
+export interface ToolParameterSchema {
+    type: ToolParameterType | readonly ToolParameterType[];
+    description?: string;
+    enum?: string[];
+    items?: ToolParameterSchema;
+    properties?: Record<string, ToolParameterSchema>;
+    required?: string[];
+}
+export interface ToolParameters {
+    type: 'object';
+    properties: Record<string, ToolParameterSchema>;
+    required?: string[];
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: ToolParameters;
+    autoApprove?: boolean;
+    skillGated?: boolean;
+    rootsRequired?: boolean;
+    writeRootsRequired?: boolean;
+    externalWrite?: boolean;
+    owningSkill?: string;
+    toolset: Toolset | null;
+    validate?: (args: Record<string, unknown>, ctx?: ToolExecuteContext) => string | null;
+    effect: (args: Record<string, unknown>, ctx?: ToolExecuteContext) => ToolEffect;
+    resource?: (args: Record<string, unknown>) => ResourceDescriptor | null;
+    compiled?: true;
+    execute: (args: Record<string, unknown>, ctx?: ToolExecuteContext) => Promise<unknown>;
+}
+export type ToolCallEvent = {
+    type: 'tool-call';
+    name: string;
+    args: Record<string, unknown>;
+    rawCall?: string | undefined;
+    effect?: ToolEffect | undefined;
+    display?: ToolCallDisplay | undefined;
+};
+export type ToolResultEvent = {
+    type: 'tool-result';
+    name: string;
+    result: unknown;
+};
+export type ToolActivityEvent = {
+    type: 'tool-activity';
+    name: string;
+    args: Record<string, unknown>;
+    resource: ResourceDescriptor | null;
+    effect: ToolEffect;
+    decision: ToolDecision;
+};
+export type ErrorEvent = {
+    type: 'error';
+    message: string;
+};
+export type AbortedEvent = {
+    type: 'aborted';
+};
+export type MetricsEvent = {
+    type: 'metrics';
+    totalTokens: number;
+    durationMs: number;
+    timeToFirstToken?: number | undefined;
+    tokensPerSecond?: number | undefined;
+    promptTokensPerSecond?: number | undefined;
+    promptTokens?: number | undefined;
+    cacheTokens?: number | undefined;
+    ctxSize?: number | undefined;
+    backends?: RunBackendUse[] | undefined;
+    usage?: UsageBreakdown | undefined;
+};
+export type CompletionEvent = TextEvent | ToolCallEvent | ToolResultEvent | ToolActivityEvent | ErrorEvent | AbortedEvent | MetricsEvent;
+export interface CompletionSdkResult {
+    requestId?: string;
+    tokenStream: AsyncIterable<string>;
+    final: Promise<CompletionFinal>;
+}
+export type ResponseFormat = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    json_schema: {
+        name: string;
+        description?: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+    };
+};
+export interface CompletionSdk {
+    completion(params: {
+        modelId: string;
+        history: Message[];
+        stream: true;
+        tools?: SdkTool[] | undefined;
+        generationParams?: LlmGenerationParams | undefined;
+        responseFormat?: ResponseFormat | undefined;
+        toolDialect?: ToolDialect | undefined;
+        kvCache?: string | boolean;
+    }): CompletionSdkResult;
+    cancel?(params: {
+        requestId: string;
+    }): Promise<void>;
+}
+export interface RoundModelLease {
+    modelId: string;
+    release: () => void;
+}
+interface CompletionArgs {
+    modelId: string;
+    acquireRound?: () => Promise<RoundModelLease>;
+    model?: string;
+    agent?: Agent;
+    ctxSize?: number;
+    cacheKey?: string;
+    thinkingDefault?: string;
+    generationParams?: LlmGenerationParams;
+    responseFormat?: ResponseFormat;
+    messages: Message[];
+    tools?: ToolDefinition[];
+    skillCatalog?: readonly CompletionSkillEntry[];
+    approve?: ApproveFn;
+    attach?: AttachFn;
+    fetchAttachment?: FetchAttachmentFn;
+    ragSearch?: RagSearchFn;
+    progress?: ProgressFn;
+    askUser?: AskUserFn;
+    signal?: BareAbortSignal;
+    toolConfigs?: Record<string, Record<string, unknown>>;
+    fsRoots?: readonly DriveRoot[];
+    fsWriteRoots?: readonly DriveRoot[];
+}
+export declare function trustedSourcesFrom(history: readonly Message[]): TrustedSource[];
+export declare function toSdkTool(tool: ToolDefinition): SdkTool;
+export type CompletionSkillEntry = SkillCatalogEntry & {
+    readonly status?: SkillState;
+};
+export declare function completion(sdk: CompletionSdk, { modelId, acquireRound, model, agent, ctxSize, cacheKey, thinkingDefault, generationParams: generationParamsOverride, responseFormat, messages: storedMessages, tools: allTools, skillCatalog, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal, toolConfigs, fsRoots, fsWriteRoots }: CompletionArgs): AsyncGenerator<CompletionEvent>;
+export {};