@qvac/harness 0.1.0 → 0.1.1

package/dist-lib/lib/spawn.js

@@ -0,0 +1,71 @@
+import stowChild, {} from 'bare-supervisor/stow';
+import { connectHarness } from "./connect.js";
+import { setHarnessLog } from "./log.js";
+import { createEmbedConfig } from "./models/embed-config.js";
+export function harnessChild(entry, opts) {
+    if (opts.logger)
+        setHarnessLog(true);
+    const { runner, skillsDir, wheelsDir, sdkStorage, embedDevice, embedGpuLayers, embedBatchSize, imageModel, imageClamps, musicModel, musicClamps, llm, onIpc, logger = null, ...spec } = opts;
+    const embedConfig = createEmbedConfig({
+        device: embedDevice,
+        gpuLayers: embedGpuLayers,
+        batchSize: embedBatchSize
+    });
+    return stowChild(entry, {
+        ...spec,
+        runner,
+        args: [
+            skillsDir ?? '',
+            sdkStorage ? JSON.stringify(sdkStorage) : '',
+            JSON.stringify(embedConfig),
+            imageModel ? JSON.stringify(imageModel) : '',
+            imageClamps ? JSON.stringify(imageClamps) : '',
+            logger ? '1' : '',
+            llm ? JSON.stringify(llm) : '',
+            musicModel ? JSON.stringify(musicModel) : '',
+            musicClamps ? JSON.stringify(musicClamps) : '',
+            wheelsDir ?? ''
+        ],
+        logger,
+        create: (ipc) => {
+            onIpc?.(ipc);
+            return connectHarness(() => ipc);
+        }
+    });
+}
+export function spawnHarness(opts) {
+    const logger = opts.logger ?? null;
+    if (logger)
+        setHarnessLog(true);
+    const embedConfig = createEmbedConfig({
+        device: opts.embedDevice,
+        gpuLayers: opts.embedGpuLayers,
+        batchSize: opts.embedBatchSize
+    });
+    return connectHarness(async () => {
+        const { default: Sidecar } = await import('bare-sidecar');
+        const { wrap } = (await import('bare-stow/host'));
+        const sidecar = new Sidecar(opts.entry, [
+            opts.skillsDir ?? '',
+            JSON.stringify(opts.sdkStorage),
+            JSON.stringify(embedConfig),
+            opts.imageModel ? JSON.stringify(opts.imageModel) : '',
+            opts.imageClamps ? JSON.stringify(opts.imageClamps) : '',
+            logger ? '1' : '',
+            opts.llm ? JSON.stringify(opts.llm) : '',
+            opts.musicModel ? JSON.stringify(opts.musicModel) : '',
+            opts.musicClamps ? JSON.stringify(opts.musicClamps) : '',
+            opts.wheelsDir ?? ''
+        ]);
+        sidecar.stdout.on('data', (data) => logger?.info('harness', data.toString().trimEnd()));
+        sidecar.stderr.on('data', (data) => logger?.warn('harness', data.toString().trimEnd()));
+        const ipc = wrap(sidecar);
+        const died = new Promise((resolve) => {
+            sidecar.once('exit', (code) => resolve(`harness exited (${code}) before ready`));
+        });
+        const failure = await Promise.race([ipc.ready.then(() => null), died]);
+        if (failure)
+            throw new Error(failure);
+        return ipc;
+    });
+}

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

@@ -0,0 +1,4 @@
+export declare const STAGING_DIR: string;
+export declare const STAGING_MAX_AGE_MS: number;
+export declare function stageFile(prefix: string, bytes: Uint8Array): Promise<string>;
+export declare function sweepStaging(now?: number): void;

package/dist-lib/lib/staging.js

@@ -0,0 +1,28 @@
+import fs from 'fs';
+import path from 'path';
+import { userTmpPath } from "./tmp-path.js";
+export const STAGING_DIR = userTmpPath('qvac-harness-staging');
+export const STAGING_MAX_AGE_MS = 60 * 60 * 1000;
+const noop = () => { };
+export async function stageFile(prefix, bytes) {
+    await fs.promises.mkdir(STAGING_DIR, { recursive: true, mode: 0o700 });
+    const unique = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    const file = path.join(STAGING_DIR, `${prefix}-${unique}`);
+    await fs.promises.writeFile(file, bytes, { mode: 0o600 });
+    return file;
+}
+export function sweepStaging(now = Date.now()) {
+    fs.promises.readdir(STAGING_DIR).then((names) => {
+        for (const name of names) {
+            const file = path.join(STAGING_DIR, name);
+            fs.promises
+                .stat(file)
+                .then((stat) => {
+                if (now - stat.mtimeMs > STAGING_MAX_AGE_MS) {
+                    return fs.promises.unlink(file).catch(noop);
+                }
+            })
+                .catch(noop);
+        }
+    }, noop);
+}

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

@@ -0,0 +1,18 @@
+export declare const MODEL_CACHE_PATH_ENV = "QVAC_MODEL_CACHE_PATH";
+export declare const SDK_HOME_ENV = "SNAP_USER_COMMON";
+export type ReleaseChannel = 'prod' | 'staging' | 'dev';
+export interface StorageOverrides {
+    readonly root?: string | null;
+    readonly models?: string | null;
+}
+export interface SdkStorage {
+    readonly home: string;
+    readonly models: string;
+}
+export interface AssistantStorage {
+    readonly root: string;
+    readonly assistant: string;
+    readonly sdk: SdkStorage;
+}
+export declare function releaseChannel(environment: string): ReleaseChannel;
+export declare function resolveStorage(channel: ReleaseChannel, overrides?: StorageOverrides, env?: Readonly<Record<string, string | undefined>>): AssistantStorage;

package/dist-lib/lib/storage.js

@@ -0,0 +1,26 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import process from 'process';
+import { persistent } from 'bare-storage';
+export const MODEL_CACHE_PATH_ENV = 'QVAC_MODEL_CACHE_PATH';
+export const SDK_HOME_ENV = 'SNAP_USER_COMMON';
+export function releaseChannel(environment) {
+    if (environment === 'production' || environment === 'prod')
+        return 'prod';
+    if (environment === 'staging')
+        return 'staging';
+    return 'dev';
+}
+export function resolveStorage(channel, overrides = {}, env = process.env) {
+    const snapCommon = env[SDK_HOME_ENV];
+    const root = overrides.root ?? join(snapCommon ?? persistent(), 'qvac', channel);
+    const canonicalSdkHome = snapCommon ?? env['HOME'] ?? env['USERPROFILE'] ?? homedir();
+    return {
+        root,
+        assistant: join(root, 'assistant'),
+        sdk: {
+            home: join(root, 'sdk-home'),
+            models: overrides.models ?? join(canonicalSdkHome, '.qvac', 'models')
+        }
+    };
+}

package/dist-lib/lib/tmp-path.d.ts

@@ -0,0 +1,7 @@
+export type UserTmpOptions = {
+    readonly readOwner?: () => {
+        uid: number;
+        username: string;
+    };
+};
+export declare function userTmpPath(name: string, opts?: UserTmpOptions): string;

package/dist-lib/lib/tmp-path.js

@@ -0,0 +1,17 @@
+import os from 'os';
+import path from 'path';
+export function userTmpPath(name, opts = {}) {
+    const readOwner = opts.readOwner ?? (() => os.userInfo());
+    return path.join(os.tmpdir(), taggedName(name, readOwner));
+}
+function taggedName(name, readOwner) {
+    let owner;
+    try {
+        const { uid, username } = readOwner();
+        owner = uid >= 0 ? `u${uid}` : username.replace(/[^A-Za-z0-9_-]/g, '');
+    }
+    catch {
+        return name;
+    }
+    return owner ? `${name}-${owner}` : name;
+}

package/dist-lib/lib/tool-call-display.d.ts

@@ -0,0 +1,21 @@
+export type ToolCallDisplay = {
+    readonly label: string;
+    readonly description?: string;
+    readonly iconEmoji?: string;
+};
+export type ToolExecutionOutcome = {
+    readonly kind: 'success';
+} | {
+    readonly kind: 'error';
+    readonly message?: string;
+    readonly error?: unknown;
+} | {
+    readonly kind: 'denied';
+    readonly reason?: string;
+} | {
+    readonly kind: 'blocked';
+    readonly reason?: string;
+} | {
+    readonly kind: 'guidance';
+    readonly message: string;
+};

package/dist-lib/lib/tool-call-display.js

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

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

@@ -0,0 +1,13 @@
+import { type ToolDefinition } from '../capabilities/completion.ts';
+import type { Toolset } from './toolsets.ts';
+export interface ToolCatalogEntry {
+    name: string;
+    description: string;
+    skillGated: boolean;
+    scopeRequired: boolean;
+    rootsRequired: boolean;
+    writeRootsRequired: boolean;
+    toolset: Toolset | null;
+    promptChars: number;
+}
+export declare function toolCatalog(tools: ReadonlyArray<ToolDefinition>): ToolCatalogEntry[];

package/dist-lib/lib/tools/catalog.js

@@ -0,0 +1,13 @@
+import { toSdkTool } from "../capabilities/completion.js";
+export function toolCatalog(tools) {
+    return tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        skillGated: tool.skillGated === true,
+        scopeRequired: false,
+        rootsRequired: tool.rootsRequired === true,
+        writeRootsRequired: tool.writeRootsRequired === true,
+        toolset: tool.toolset,
+        promptChars: JSON.stringify(toSdkTool(tool)).length
+    }));
+}

package/dist-lib/lib/tools/create-documents.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../capabilities/completion.ts';
+import { type FsToolOptions } from './fs/scope.ts';
+export declare function createCreateDocumentsTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;

package/dist-lib/lib/tools/create-documents.js

@@ -0,0 +1,87 @@
+import { canonicalDenyRoots, defaultRealpath, resolveKey } from "./fs/scope.js";
+import { writeText } from "./fs/write.js";
+function documentRequests(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    const documents = [];
+    for (const entry of raw) {
+        const record = entry;
+        if (typeof record?.path !== 'string' || !record.path.trim())
+            return null;
+        if (typeof record.content !== 'string')
+            return null;
+        documents.push({ path: record.path, content: record.content });
+    }
+    return documents;
+}
+export function createCreateDocumentsTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'create_documents',
+        toolset: 'files',
+        description: 'Create new files inside the granted directories. Parent directories are ' +
+            'created as needed. Fails per file if the file already exists — use ' +
+            'edit_documents to change existing files.',
+        parameters: {
+            type: 'object',
+            properties: {
+                documents: {
+                    type: 'array',
+                    description: 'Files to create',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'File path' },
+                            content: { type: 'string', description: 'Full file content' }
+                        },
+                        required: ['path', 'content']
+                    }
+                }
+            },
+            required: ['documents']
+        },
+        effect: () => 'read',
+        writeRootsRequired: true,
+        validate(rawArgs) {
+            return documentRequests(rawArgs.documents)
+                ? null
+                : 'documents must be a non-empty array of { path, content }';
+        },
+        resource(args) {
+            const documents = documentRequests(args.documents);
+            if (!documents)
+                return null;
+            const bytes = documents.reduce((sum, doc) => sum + doc.content.length, 0);
+            const first = documents[0];
+            const suffix = documents.length > 1 ? ` (+${documents.length - 1} more)` : '';
+            return { kind: 'file', label: `create ${first.path}${suffix}, ${bytes} chars` };
+        },
+        async execute(rawArgs, ctx) {
+            const roots = ctx?.fsWriteRoots ?? [];
+            const documents = documentRequests(rawArgs.documents);
+            if (!documents)
+                return { error: 'documents must be a non-empty array of { path, content }' };
+            const created = [];
+            const failed = [];
+            const deny = await canonicalDenyRoots(deniedRoots, realpath);
+            for (const doc of documents) {
+                const resolved = await resolveKey(doc.path, roots, realpath, deny);
+                if ('error' in resolved) {
+                    failed.push({ path: doc.path, error: resolved.error });
+                    continue;
+                }
+                try {
+                    if ((await resolved.root.drive.entry(resolved.key)) !== null) {
+                        failed.push({ path: doc.path, error: 'file already exists' });
+                        continue;
+                    }
+                    await writeText(resolved.root.drive, resolved.key, doc.content);
+                    created.push(doc.path);
+                }
+                catch (err) {
+                    failed.push({ path: doc.path, error: err.message });
+                }
+            }
+            return { created, ...(failed.length ? { failed } : {}) };
+        }
+    };
+}

package/dist-lib/lib/tools/edit-documents.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../capabilities/completion.ts';
+import { type FsToolOptions } from './fs/scope.ts';
+export declare function createEditDocumentsTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;

package/dist-lib/lib/tools/edit-documents.js

@@ -0,0 +1,122 @@
+import b4a from 'b4a';
+import { canonicalDenyRoots, defaultRealpath, resolveKey } from "./fs/scope.js";
+import { writeText } from "./fs/write.js";
+function editRequests(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    const edits = [];
+    for (const entry of raw) {
+        const record = entry;
+        if (typeof record?.path !== 'string' || !record.path.trim())
+            return null;
+        if (typeof record.search !== 'string' || record.search.length === 0)
+            return null;
+        if (typeof record.replace !== 'string')
+            return null;
+        edits.push({ path: record.path, search: record.search, replace: record.replace });
+    }
+    return edits;
+}
+function applyEdits(content, edits) {
+    let next = content;
+    for (const edit of edits) {
+        const first = next.indexOf(edit.search);
+        if (first === -1)
+            return { error: 'search text not found' };
+        if (next.indexOf(edit.search, first + edit.search.length) !== -1) {
+            return { error: 'search text is ambiguous (matches more than once)' };
+        }
+        next = next.slice(0, first) + edit.replace + next.slice(first + edit.search.length);
+    }
+    return next;
+}
+export function createEditDocumentsTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'edit_documents',
+        toolset: 'files',
+        description: 'Edit existing files inside the granted directories via search/replace. ' +
+            'Each search string must match exactly once in its file; include enough ' +
+            'surrounding context to make it unique. Edits to one file apply together.',
+        parameters: {
+            type: 'object',
+            properties: {
+                edits: {
+                    type: 'array',
+                    description: 'Search/replace edits',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'File path' },
+                            search: { type: 'string', description: 'Exact text to find (must match once)' },
+                            replace: { type: 'string', description: 'Replacement text' }
+                        },
+                        required: ['path', 'search', 'replace']
+                    }
+                }
+            },
+            required: ['edits']
+        },
+        effect: () => 'write',
+        autoApprove: false,
+        writeRootsRequired: true,
+        validate(rawArgs) {
+            return editRequests(rawArgs.edits)
+                ? null
+                : 'edits must be a non-empty array of { path, search, replace }';
+        },
+        resource(args) {
+            const edits = editRequests(args.edits);
+            if (!edits)
+                return null;
+            const paths = [...new Set(edits.map((edit) => edit.path))];
+            const label = paths.slice(0, 3).join(', ');
+            return {
+                kind: 'file',
+                label: `edit ${paths.length > 3 ? `${label} (+${paths.length - 3} more)` : label} (${edits.length} edit${edits.length > 1 ? 's' : ''})`
+            };
+        },
+        async execute(rawArgs, ctx) {
+            const roots = ctx?.fsWriteRoots ?? [];
+            const edits = editRequests(rawArgs.edits);
+            if (!edits)
+                return { error: 'edits must be a non-empty array of { path, search, replace }' };
+            const byPath = new Map();
+            for (const edit of edits) {
+                const list = byPath.get(edit.path) ?? [];
+                list.push(edit);
+                byPath.set(edit.path, list);
+            }
+            const edited = [];
+            const failed = [];
+            const deny = await canonicalDenyRoots(deniedRoots, realpath);
+            for (const [file, fileEdits] of byPath) {
+                const resolved = await resolveKey(file, roots, realpath, deny);
+                if ('error' in resolved) {
+                    failed.push({ path: file, error: resolved.error });
+                    continue;
+                }
+                try {
+                    const entry = await resolved.root.drive.entry(resolved.key);
+                    const blob = entry === null ? null : await resolved.root.drive.get(resolved.key);
+                    if (entry === null || blob === null) {
+                        failed.push({ path: file, error: `no such file: ${file}` });
+                        continue;
+                    }
+                    const next = applyEdits(b4a.toString(blob, 'utf8'), fileEdits);
+                    if (typeof next === 'object') {
+                        failed.push({ path: file, error: next.error });
+                        continue;
+                    }
+                    await writeText(resolved.root.drive, resolved.key, next, {
+                        executable: entry.value.executable
+                    });
+                    edited.push(file);
+                }
+                catch (err) {
+                    failed.push({ path: file, error: err.message });
+                }
+            }
+            return { edited, ...(failed.length ? { failed } : {}) };
+        }
+    };
+}

package/dist-lib/lib/tools/edit-image.d.ts

@@ -0,0 +1,25 @@
+import type { ToolDefinition } from '../capabilities/completion.ts';
+import type { ImageClamps } from '../models/model-catalog.ts';
+import { type DiffusionRuntime } from './generate-image.ts';
+interface Rgba {
+    width: number;
+    height: number;
+    data: Buffer;
+    frames?: Rgba[];
+}
+interface Media {
+    image: {
+        decode(input: Buffer, opts?: {
+            maxFrames?: number;
+        }): Promise<Rgba>;
+        encode(rgba: Rgba, opts: {
+            mimetype: string;
+        }): Promise<Uint8Array>;
+    };
+}
+export interface EditImageDeps {
+    loadMedia?: () => Promise<Media | null>;
+    resample?: (rgba: Rgba, width: number, height: number) => Rgba | Promise<Rgba>;
+}
+export declare function createEditImageTool(runtime: DiffusionRuntime, { loadMedia, resample }?: EditImageDeps, clamps?: ImageClamps): ToolDefinition;
+export {};