@qvac/harness 0.1.0 → 0.1.2

package/dist-lib/lib/web-search/url-helpers.js

@@ -0,0 +1,11 @@
+export function urlMatchesHost(url, host) {
+    let hostname;
+    try {
+        hostname = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    const target = host.toLowerCase();
+    return hostname === target || hostname.endsWith(`.${target}`);
+}

package/dist-lib/lib/web-search/url-normalize.d.ts

@@ -0,0 +1 @@
+export declare function normalizeUrl(raw: string): string;

package/dist-lib/lib/web-search/url-normalize.js

@@ -0,0 +1,25 @@
+const TRACKING_PARAM_RE = /^(utm_\w+|fbclid|gclid)$/i;
+function stripTrackingParams(search) {
+    if (!search) {
+        return '';
+    }
+    const kept = search
+        .slice(1)
+        .split('&')
+        .filter((pair) => {
+        const key = pair.split('=')[0] || '';
+        return !TRACKING_PARAM_RE.test(key);
+    });
+    return kept.length > 0 ? `?${kept.join('&')}` : '';
+}
+export function normalizeUrl(raw) {
+    try {
+        const u = new URL(raw);
+        const host = u.hostname.toLowerCase().replace(/^www\./, '');
+        const search = stripTrackingParams(u.search);
+        return host + u.pathname.replace(/\/+$/, '') + search;
+    }
+    catch {
+        return raw;
+    }
+}

package/dist-lib/lib/web-search/user-agents.d.ts

@@ -0,0 +1,3 @@
+export declare const BROWSER_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
+export declare const GOOGLE_GSA_UA = "Mozilla/5.0 (Linux; Android 12; SM-S901U) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/99.0.4844.88 Mobile Safari/537.36 NSTNWV";
+export declare const SAFARI_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Safari/605.1.15";

package/dist-lib/lib/web-search/user-agents.js

@@ -0,0 +1,3 @@
+export const BROWSER_UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36';
+export const GOOGLE_GSA_UA = 'Mozilla/5.0 (Linux; Android 12; SM-S901U) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/99.0.4844.88 Mobile Safari/537.36 NSTNWV';
+export const SAFARI_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Safari/605.1.15';

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

@@ -0,0 +1,50 @@
+import type { HarnessEvent } from './contract-types.ts';
+export interface WireEvent {
+    type: string;
+    text?: string | null;
+    name?: string | null;
+    arguments?: unknown;
+    result?: unknown;
+    callId?: string | null;
+    resource?: {
+        kind: string;
+        label: string;
+    } | null;
+    message?: string | null;
+    metrics?: unknown;
+    path?: string | null;
+    fileName?: string | null;
+    mimeType?: string | null;
+    raw?: boolean | null;
+    attachmentId?: string | null;
+    meta?: boolean | null;
+    byteLength?: number | null;
+    percentage?: number | null;
+    cleared?: boolean | null;
+    query?: string | null;
+    limit?: number | null;
+    question?: string | null;
+    options?: unknown;
+    effect?: string | null;
+    op?: string | null;
+    payload?: unknown;
+    decision?: string | null;
+    rawCall?: string | null;
+    intent?: string | null;
+    display?: unknown;
+}
+export interface WireDownloadEvent {
+    type: string;
+    progress?: unknown;
+    assetId?: string | null;
+    message?: string | null;
+}
+export declare function toWire(event: HarnessEvent): WireEvent;
+export declare function fromWire(event: WireEvent): HarnessEvent;
+export declare function toDownloadWire(event: HarnessEvent): WireDownloadEvent;
+export declare function fromDownloadWire(event: WireDownloadEvent): HarnessEvent;
+export declare function packVectors(vectors: number[][]): {
+    dimensions: number;
+    vectors: Buffer;
+};
+export declare function unpackVectors(dimensions: number, bytes: Buffer): number[][];

package/dist-lib/lib/wire.js

@@ -0,0 +1,145 @@
+import b4a from 'b4a';
+export function toWire(event) {
+    switch (event.type) {
+        case 'content':
+        case 'thinking':
+            return { type: event.type, text: event.text };
+        case 'tool-call':
+            return {
+                type: 'tool-call',
+                name: event.name,
+                arguments: event.args,
+                rawCall: event.rawCall ?? null,
+                effect: event.effect ?? null,
+                display: event.display
+            };
+        case 'tool-result':
+            return {
+                type: 'tool-result',
+                name: event.name,
+                result: event.result
+            };
+        case 'tool-activity':
+            return {
+                type: 'tool-activity',
+                name: event.name,
+                arguments: event.args,
+                resource: event.resource ?? null,
+                effect: event.effect,
+                decision: event.decision
+            };
+        case 'metrics': {
+            const { type, ...metrics } = event;
+            return { type, metrics };
+        }
+        case 'error':
+            return { type: 'error', message: event.message };
+        case 'aborted':
+            return { type: 'aborted' };
+        default:
+            return { type: 'error', message: `unmapped harness event: ${event.type}` };
+    }
+}
+export function fromWire(event) {
+    switch (event.type) {
+        case 'content':
+        case 'thinking':
+            return { type: event.type, text: event.text ?? '' };
+        case 'tool-call':
+            return {
+                type: 'tool-call',
+                name: event.name ?? '',
+                args: event.arguments ?? {},
+                ...(event.rawCall === null || event.rawCall === undefined
+                    ? {}
+                    : { rawCall: event.rawCall }),
+                effect: event.effect === 'read' ? 'read' : 'write',
+                display: event.display ?? undefined
+            };
+        case 'tool-result':
+            return {
+                type: 'tool-result',
+                name: event.name ?? '',
+                result: event.result
+            };
+        case 'tool-activity':
+            return {
+                type: 'tool-activity',
+                name: event.name ?? '',
+                args: event.arguments ?? {},
+                resource: event.resource ?? null,
+                effect: event.effect === 'read' ? 'read' : 'write',
+                decision: event.decision || 'blocked'
+            };
+        case 'metrics':
+            return { type: 'metrics', ...event.metrics };
+        case 'error':
+            return { type: 'error', message: event.message ?? 'harness error' };
+        case 'aborted':
+            return { type: 'aborted' };
+        default:
+            return { type: event.type };
+    }
+}
+export function toDownloadWire(event) {
+    switch (event.type) {
+        case 'progress': {
+            const { type, ...progress } = event;
+            return { type, progress };
+        }
+        case 'complete':
+            return { type: 'complete', assetId: event.assetId };
+        case 'error':
+            return { type: 'error', message: event.message };
+        case 'aborted':
+            return { type: 'aborted' };
+        default:
+            return { type: 'error', message: `unmapped download event: ${event.type}` };
+    }
+}
+export function fromDownloadWire(event) {
+    switch (event.type) {
+        case 'progress':
+            return { type: 'progress', ...(event.progress ?? {}) };
+        case 'complete':
+            return { type: 'complete', assetId: event.assetId ?? '' };
+        case 'error':
+            return { type: 'error', message: event.message ?? 'download error' };
+        case 'aborted':
+            return { type: 'aborted' };
+        default:
+            return { type: event.type };
+    }
+}
+export function packVectors(vectors) {
+    const dimensions = vectors[0]?.length ?? 0;
+    const bytes = b4a.alloc(vectors.length * dimensions * 4);
+    let offset = 0;
+    for (const vector of vectors) {
+        if (vector.length !== dimensions) {
+            throw new Error('embed returned ragged vectors — every row must share one dimension');
+        }
+        for (const value of vector) {
+            b4a.writeFloatLE(bytes, value, offset);
+            offset += 4;
+        }
+    }
+    return { dimensions, vectors: bytes };
+}
+export function unpackVectors(dimensions, bytes) {
+    if (dimensions === 0)
+        return [];
+    const rowBytes = dimensions * 4;
+    if (bytes.byteLength % rowBytes !== 0) {
+        throw new Error('embed response length does not match its dimensions');
+    }
+    const rows = [];
+    for (let offset = 0; offset < bytes.byteLength; offset += rowBytes) {
+        const row = [];
+        for (let index = 0; index < dimensions; index++) {
+            row.push(b4a.readFloatLE(bytes, offset + index * 4));
+        }
+        rows.push(row);
+    }
+    return rows;
+}

package/dist-lib/schema/baseline.d.ts

@@ -0,0 +1,8 @@
+interface RewindOptions {
+    readonly carries: string;
+    readonly keep: readonly string[];
+}
+export declare function rewindSpec(root: string, dirs: string[], { carries, keep }: RewindOptions): string[];
+export declare function unstageSpec(root: string, dirs: string[]): void;
+export declare function resetHrpcIds(hrpcDir: string): void;
+export {};

package/dist-lib/schema/baseline.js

@@ -0,0 +1,35 @@
+import fs from 'bare-fs';
+import path from 'bare-path';
+import process from 'bare-process';
+import { spawnSync } from 'bare-subprocess';
+import { previousReleaseTags } from "./release-tags.js";
+export function rewindSpec(root, dirs, { carries, keep }) {
+    if (process.env.SCHEMA_NO_BASELINE)
+        return [];
+    const baselines = previousReleaseTags(root, { carries });
+    if (baselines.length === 0)
+        return [];
+    const held = keep.map((file) => {
+        const target = path.join(root, file);
+        return { target, contents: fs.readFileSync(target) };
+    });
+    for (const dir of dirs)
+        checkoutSpec(root, dir, baselines[0]);
+    for (const { target, contents } of held)
+        fs.writeFileSync(target, contents);
+    return baselines;
+}
+function checkoutSpec(root, dir, tag) {
+    console.log(`rewinding ${path.relative(root, dir)} to ${tag}`);
+    const done = spawnSync('git', ['checkout', tag, '--', dir], { cwd: root });
+    if (done.status !== 0)
+        throw new Error(`checkout ${tag} failed: ${done.stderr ?? ''}`);
+}
+export function unstageSpec(root, dirs) {
+    const done = spawnSync('git', ['reset', '--quiet', 'HEAD', '--', ...dirs], { cwd: root });
+    if (done.status !== 0)
+        throw new Error(`git reset -- spec failed: ${done.stderr ?? ''}`);
+}
+export function resetHrpcIds(hrpcDir) {
+    fs.rmSync(path.join(hrpcDir, 'hrpc.json'), { force: true });
+}

package/dist-lib/schema/build.d.ts

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

package/dist-lib/schema/build.js

@@ -0,0 +1,39 @@
+import path from 'bare-path';
+import { fileURLToPath } from 'bare-url';
+import HRPCBuilder from 'hrpc';
+import Hyperschema from 'hyperschema';
+import HyperschemaTS from 'hyperschema-ts';
+import { resetHrpcIds, rewindSpec, unstageSpec } from "./baseline.js";
+import { writeBind, writeClient } from "./generate.js";
+import { registerHarnessApi, registerHarnessTypes } from "./harness.js";
+const dir = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.join(dir, '..');
+const SPEC_DIR = path.join(dir, '..', 'spec');
+const SCHEMA_DIR = path.join(SPEC_DIR, 'hyperschema');
+const HRPC_DIR = path.join(SPEC_DIR, 'hrpc');
+const BASELINE_DIRS = [SPEC_DIR];
+const HAND_WRITTEN = [
+    'spec/index.js',
+    'spec/index.d.ts',
+    'spec/calls.d.ts',
+    'spec/bind.d.ts',
+    'spec/hrpc/index.d.ts',
+    'spec/hrpc/messages.d.ts'
+];
+const baselines = rewindSpec(ROOT, BASELINE_DIRS, {
+    carries: 'spec/hyperschema/schema.json',
+    keep: HAND_WRITTEN
+});
+const schema = Hyperschema.from(SCHEMA_DIR);
+registerHarnessTypes(schema.namespace('harness'));
+Hyperschema.toDisk(schema, { esm: true });
+HyperschemaTS.toDisk(schema);
+resetHrpcIds(HRPC_DIR);
+const builder = HRPCBuilder.from(SCHEMA_DIR, HRPC_DIR);
+registerHarnessApi(builder.namespace('harness'));
+HRPCBuilder.toDisk(builder);
+writeBind(builder, path.join(SPEC_DIR, 'bind.js'));
+writeClient(builder, path.join(SPEC_DIR, 'calls.js'), 'harnessClient');
+if (baselines.length > 0)
+    unstageSpec(ROOT, BASELINE_DIRS);
+console.log('harness contract spec generated under spec/');

package/dist-lib/schema/generate.d.ts

@@ -0,0 +1,20 @@
+interface HRPCHandler {
+    name: string;
+    request?: {
+        name: string;
+        send?: boolean;
+        stream?: boolean;
+    };
+    response?: {
+        name: string;
+        stream?: boolean;
+    };
+}
+interface HRPCBuilderLike {
+    handlers: ReadonlyArray<HRPCHandler>;
+}
+export declare function writeBind(builder: HRPCBuilderLike, outFile: string): void;
+export declare function writeClient(builder: HRPCBuilderLike, outFile: string, exportName?: string): void;
+export declare function writeCapabilities(builder: HRPCBuilderLike, outFile: string): void;
+export declare function writeConfigTypes(outFile: string): void;
+export {};

package/dist-lib/schema/generate.js

@@ -0,0 +1,149 @@
+import fs from 'bare-fs';
+function tsName(fqn) {
+    return fqn
+        .slice(1)
+        .split(/[/-]/)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+function camel(name, prefix = '') {
+    const base = name.startsWith('@') ? name.slice(name.indexOf('/') + 1) : name;
+    const parts = base.split(/[/-]/);
+    const cased = parts.map((part, i) => i === 0 && prefix.length === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1));
+    return prefix + cased.join('');
+}
+const HEADER = '// This file is autogenerated by schema/build.js\n// Do not edit manually.\n\n';
+export function writeBind(builder, outFile) {
+    let s = `${HEADER}import { pipeline, Readable } from "streamx";\n\nfunction noop() {}\n\nexport function bindApi(rpc, api) {\n`;
+    for (const handler of builder.handlers) {
+        const on = camel(handler.name, 'on');
+        const method = camel(handler.name);
+        if (handler.request?.send) {
+            throw new Error(`generate: command "${handler.name}" uses send-only, not supported yet`);
+        }
+        s += `  if (api.${method}) {\n`;
+        if (handler.request?.stream && handler.response?.stream) {
+            s += `    rpc.${on}((stream) => {\n`;
+            s += '      stream.on("error", noop);\n';
+            s += '      (async () => {\n';
+            s += '        try {\n';
+            s += `          for await (const frame of api.${method}(stream)) {\n`;
+            s += '            stream.write(frame);\n';
+            s += '          }\n';
+            s += '          stream.end();\n';
+            s += '        } catch (err) {\n';
+            s += '          stream.destroy(err);\n';
+            s += '        }\n';
+            s += '      })();\n';
+            s += '    });\n';
+        }
+        else if (handler.request?.stream) {
+            throw new Error(`generate: command "${handler.name}" uses request streaming without response streaming, not supported yet`);
+        }
+        else if (handler.response?.stream) {
+            s += `    rpc.${on}((out) => {\n`;
+            s += `      const src = Readable.from(api.${method}(out.data));\n`;
+            s += '      src.on("error", (err) => out.writeStream?.destroy(err));\n';
+            s += '      pipeline(src, out, noop);\n';
+            s += '      out.writeStream?.on("close", () => src.destroy());\n';
+            s += '    });\n';
+        }
+        else {
+            s += `    rpc.${on}((req) => api.${method}(req));\n`;
+        }
+        s += '  }\n';
+    }
+    s += '}\n';
+    fs.writeFileSync(outFile, s);
+}
+export function writeClient(builder, outFile, exportName = 'engineClient') {
+    let s = `${HEADER}function noop() {}\n\nfunction armed(stream) {\n  stream.on("error", noop);\n  return stream;\n}\n\nexport function ${exportName}(rpc) {\n  return {\n`;
+    for (const handler of builder.handlers) {
+        const method = camel(handler.name);
+        if (handler.request?.stream && handler.response?.stream) {
+            s += `    ${method}: () => armed(rpc.${method}()),\n`;
+        }
+        else if (handler.response?.stream) {
+            s += `    ${method}: (input) => armed(rpc.${method}(input)),\n`;
+        }
+        else {
+            s += `    ${method}: (input) => rpc.${method}(input),\n`;
+        }
+    }
+    s += '  };\n}\n';
+    fs.writeFileSync(outFile, s);
+}
+export function writeCapabilities(builder, outFile) {
+    let s = HEADER;
+    s += "import type * as T from './hyperschema/types.d.ts'\n\n";
+    s +=
+        '// the generated client pre-arms an error observer - a dying stream never crashes a host that only listens to data\n';
+    s += 'export interface WatchStream<Frame> extends AsyncIterable<Frame> {\n';
+    s += "  on(event: 'data', listener: (frame: Frame) => void): this\n";
+    s += "  on(event: 'error', listener: (err: Error) => void): this\n";
+    s += "  on(event: 'close' | 'end', listener: () => void): this\n";
+    s += "  off(event: 'data', listener: (frame: Frame) => void): this\n";
+    s += "  off(event: 'error', listener: (err: Error) => void): this\n";
+    s += "  off(event: 'close' | 'end', listener: () => void): this\n";
+    s += '  destroy(): void\n';
+    s += '}\n\n';
+    s += 'export interface UploadStream<In, Out> extends WatchStream<Out> {\n';
+    s += '  write(frame: In): boolean\n';
+    s += '  end(): void\n';
+    s += '}\n\n';
+    s +=
+        '// what hrpc hands a duplex handler (its own async iterator hangs - see api/attachments.ts)\n';
+    s += 'export interface HandlerFrames<Frame> {\n';
+    s += "  on(event: 'data', listener: (frame: Frame) => void): void\n";
+    s += "  on(event: 'end', listener: () => void): void\n";
+    s += "  on(event: 'error', listener: (err: Error) => void): void\n";
+    s += '}\n\n';
+    let client = 'export interface Capabilities {\n';
+    let server = 'export interface CapabilityHandlers {\n';
+    for (const handler of builder.handlers) {
+        if (handler.request?.send) {
+            throw new Error(`generate: command "${handler.name}" uses send-only, not supported yet`);
+        }
+        if (!handler.request || !handler.response) {
+            throw new Error(`generate: command "${handler.name}" is missing a request or response type`);
+        }
+        const method = camel(handler.name);
+        const req = `T.${tsName(handler.request.name)}`;
+        const res = `T.${tsName(handler.response.name)}`;
+        const input = handler.request.name === '@assistant/empty' ? `input?: ${req}` : `input: ${req}`;
+        if (handler.request?.stream && handler.response?.stream) {
+            client += `  ${method}(): UploadStream<${req}, ${res}>\n`;
+            server += `  ${method}(stream: AsyncIterable<${req}> | HandlerFrames<${req}>): AsyncIterable<${res}>\n`;
+        }
+        else if (handler.response?.stream) {
+            client += `  ${method}(${input}): WatchStream<${res}>\n`;
+            server += `  ${method}(${input}): AsyncIterable<${res}>\n`;
+        }
+        else {
+            client += `  ${method}(${input}): Promise<${res}>\n`;
+            server += `  ${method}(${input}): ${res} | Promise<${res}>\n`;
+        }
+    }
+    client += '}\n';
+    server += '}\n';
+    s += client + '\n' + server;
+    fs.writeFileSync(outFile, s);
+}
+export function writeConfigTypes(outFile) {
+    fs.writeFileSync(outFile, `import type { Codec } from 'compact-encoding'
+
+export interface ConfConfig {
+  minSupportedVersion: string
+}
+
+declare const spec: {
+  production: ConfConfig
+  // never set: the reader always asks for the production slot
+  development: null
+  productionEncoding: Codec<ConfConfig>
+  developmentEncoding: null
+}
+
+export default spec
+`);
+}

package/dist-lib/schema/harness.d.ts

@@ -0,0 +1,2 @@
+export declare function registerHarnessTypes(ns: any): void;
+export declare function registerHarnessApi(api: any): void;