@qvac/harness 0.1.0 → 0.1.2

package/dist-lib/lib/tools/operations/gmail-message.js

@@ -0,0 +1,62 @@
+import b4a from 'b4a';
+import { z } from 'zod';
+const AddressList = z.union([z.string(), z.array(z.string())]);
+export const GmailEnvelopeSchema = z
+    .object({
+    to: AddressList,
+    cc: AddressList.optional(),
+    bcc: AddressList.optional(),
+    subject: z.string(),
+    text: z.string().optional(),
+    html: z.string().optional(),
+    from: z.string().optional(),
+    replyTo: z.string().optional(),
+    inReplyTo: z.string().optional(),
+    references: z.string().optional()
+})
+    .refine((value) => Boolean(value.text?.length) || Boolean(value.html?.length));
+export function buildGmailMessage(envelope) {
+    return [...headerLines(envelope), ...bodyLines(envelope)].join('\r\n');
+}
+function stripNewlines(value) {
+    return value.replace(/[\r\n]+/g, ' ');
+}
+function joinAddresses(value) {
+    if (value === undefined)
+        return undefined;
+    const parts = (Array.isArray(value) ? value : [value])
+        .map((entry) => stripNewlines(String(entry)).trim())
+        .filter((entry) => entry.length > 0);
+    return parts.length > 0 ? parts.join(', ') : undefined;
+}
+function encodeHeaderValue(value) {
+    const sanitized = stripNewlines(value);
+    if (/^[\x20-\x7e]*$/.test(sanitized))
+        return sanitized;
+    return `=?UTF-8?B?${b4a.toString(b4a.from(sanitized, 'utf8'), 'base64')}?=`;
+}
+function headerLines(envelope) {
+    const headers = [
+        ['To', joinAddresses(envelope.to)],
+        ['Cc', joinAddresses(envelope.cc)],
+        ['Bcc', joinAddresses(envelope.bcc)],
+        ['From', envelope.from],
+        ['Reply-To', envelope.replyTo],
+        ['Subject', encodeHeaderValue(envelope.subject)],
+        ['In-Reply-To', envelope.inReplyTo],
+        ['References', envelope.references]
+    ];
+    return headers
+        .filter((entry) => entry[1] !== undefined)
+        .map(([name, value]) => `${name}: ${stripNewlines(value)}`);
+}
+function bodyLines(envelope) {
+    const useHtml = !envelope.text && Boolean(envelope.html);
+    const content = (useHtml ? envelope.html : envelope.text) ?? '';
+    return [
+        `Content-Type: ${useHtml ? 'text/html' : 'text/plain'}; charset="UTF-8"`,
+        'MIME-Version: 1.0',
+        '',
+        content
+    ];
+}

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

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import type { ToolParameters } from '../../capabilities/completion.ts';
+declare const OperationSchema: z.ZodObject<{
+    tool: z.ZodString;
+    description: z.ZodString;
+    parameters: z.ZodType<ToolParameters, unknown, z.core.$ZodTypeInternals<ToolParameters, unknown>>;
+    request: z.ZodUnion<readonly [z.ZodObject<{
+        transport: z.ZodLiteral<"mcp">;
+        method: z.ZodString;
+        url: z.ZodString;
+        builder: z.ZodEnum<{
+            "gmail-send": "gmail-send";
+            "gmail-draft": "gmail-draft";
+            "calendar-meet-event": "calendar-meet-event";
+            "calendar-add-meet": "calendar-add-meet";
+            "docs-create": "docs-create";
+            "docs-append-text": "docs-append-text";
+            "sheets-create": "sheets-create";
+            "sheets-write-values": "sheets-write-values";
+            "sheets-append-values": "sheets-append-values";
+            "drive-create-folder": "drive-create-folder";
+            "drive-trash": "drive-trash";
+            "notion-create-page": "notion-create-page";
+            "notion-insert-content": "notion-insert-content";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        transport: z.ZodOptional<z.ZodLiteral<"http">>;
+        method: z.ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PUT: "PUT";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+        }>;
+        url: z.ZodString;
+        query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        urlDefaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        builder: z.ZodEnum<{
+            "gmail-send": "gmail-send";
+            "gmail-draft": "gmail-draft";
+            "calendar-meet-event": "calendar-meet-event";
+            "calendar-add-meet": "calendar-add-meet";
+            "docs-create": "docs-create";
+            "docs-append-text": "docs-append-text";
+            "sheets-create": "sheets-create";
+            "sheets-write-values": "sheets-write-values";
+            "sheets-append-values": "sheets-append-values";
+            "drive-create-folder": "drive-create-folder";
+            "drive-trash": "drive-trash";
+            "notion-create-page": "notion-create-page";
+            "notion-insert-content": "notion-insert-content";
+        }>;
+    }, z.core.$strip>]>;
+    response: z.ZodOptional<z.ZodObject<{
+        pick: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type OperationSpec = z.infer<typeof OperationSchema>;
+export declare function parseOperationsManifest(json: string): OperationSpec[] | null;
+export {};

package/dist-lib/lib/tools/operations/manifest.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { BUILDER_NAMES } from "./builders.js";
+const ParameterType = z.enum(['string', 'number', 'boolean', 'object', 'integer', 'array', 'null']);
+const ParameterSchema = z.lazy(() => z.object({
+    type: z.union([ParameterType, z.array(ParameterType).min(1)]),
+    description: z.string().optional(),
+    enum: z.array(z.string()).optional(),
+    items: ParameterSchema.optional(),
+    properties: z.record(z.string(), ParameterSchema).optional(),
+    required: z.array(z.string()).optional()
+}));
+const ParametersSchema = z.object({
+    type: z.literal('object'),
+    properties: z.record(z.string(), ParameterSchema),
+    required: z.array(z.string()).optional()
+});
+const HttpRequestSchema = z.object({
+    transport: z.literal('http').optional(),
+    method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
+    url: z.string().min(1),
+    query: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+    urlDefaults: z.record(z.string(), z.string()).optional(),
+    builder: z.enum(BUILDER_NAMES)
+});
+const McpRequestSchema = z.object({
+    transport: z.literal('mcp'),
+    method: z.string().min(1),
+    url: z.string().min(1),
+    builder: z.enum(BUILDER_NAMES)
+});
+const RequestSchema = z.union([McpRequestSchema, HttpRequestSchema]);
+const OperationSchema = z.object({
+    tool: z.string().min(1),
+    description: z.string().min(1),
+    parameters: ParametersSchema,
+    request: RequestSchema,
+    response: z.object({ pick: z.array(z.string().min(1)).min(1) }).optional()
+});
+const ManifestSchema = z.object({ operations: z.array(OperationSchema) });
+export function parseOperationsManifest(json) {
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    const parsed = ManifestSchema.safeParse(value);
+    return parsed.success ? parsed.data.operations : null;
+}

package/dist-lib/lib/tools/outbound-guard.d.ts

@@ -0,0 +1,10 @@
+export declare const REFUSAL = "Refusing to send:";
+export type TrustedOrigin = 'user' | 'tool-result' | 'skill';
+export type TrustedSource = {
+    origin: TrustedOrigin;
+    text: string;
+};
+export interface GuardOptions {
+    externalWrite?: boolean;
+}
+export declare function guardToolCall(toolName: string, args: Record<string, unknown>, sources: readonly TrustedSource[], { externalWrite }?: GuardOptions): string | null;

package/dist-lib/lib/tools/outbound-guard.js

@@ -0,0 +1,127 @@
+import { grounded } from 'asenion';
+import { decodeBase64, printableRatio, strings } from 'asenion/guards';
+import { READ_METHODS } from "./http-methods.js";
+const ADDRESS = /[^\s<>,;:"'\\]{1,64}@[^\s<>,;:"'\\]{1,255}\.[A-Za-z]{2,24}/g;
+const PRINTABLE_RATIO = 0.9;
+const RESERVED_DOMAINS = new Set(['example.com', 'example.net', 'example.org']);
+const RESERVED_TLDS = ['example', 'invalid', 'test', 'localhost'];
+const OUTBOUND_TOOLS = new Set(['http_request', 'mcp_call']);
+const MCP_READ_METHOD = /^(tools\/list|resources\/\w+|(get|list|search|read|find|fetch)[_.-])/i;
+const HINT_LIMIT = 5;
+export const REFUSAL = 'Refusing to send:';
+export function guardToolCall(toolName, args, sources, { externalWrite = false } = {}) {
+    if (!externalWrite && !isOutbound(toolName, args))
+        return null;
+    const addresses = unique(scanPayload(args));
+    if (!addresses.length)
+        return null;
+    const reserved = addresses.find((value) => isReserved(key(value)));
+    if (reserved) {
+        return `${REFUSAL} ${mask(reserved)} is a reserved documentation domain (RFC 2606) that cannot receive mail — a placeholder copied from an example, not a real address. Ask the user for the actual address.`;
+    }
+    const trusted = addressesIn(sources, (origin) => origin !== 'skill');
+    const unverified = addresses.filter((value) => !grounded(value, trusted).ok);
+    if (!unverified.length)
+        return null;
+    if (alreadyRefusedThisTurn(sources)) {
+        return `${REFUSAL} ${masked(unverified)} still cannot be verified, and an earlier call in this turn was already refused for the same reason. Stop calling this tool. Reply to the user in plain text and ask them for the address.`;
+    }
+    const fromSkill = addressesIn(sources, (origin) => origin === 'skill');
+    const placeholders = unverified.filter((value) => grounded(value, fromSkill).ok);
+    if (placeholders.length) {
+        return `${REFUSAL} ${masked(placeholders)} appears only in the skill's own documentation — an example placeholder, not a real address. Ask the user for the actual address.`;
+    }
+    const spoofed = unverified.filter((value) => lookalikeOf(value, trusted) !== undefined);
+    if (spoofed.length)
+        return drawnLike(spoofed, trusted);
+    return invented(unverified, trusted);
+}
+function lookalikeOf(value, trusted) {
+    return grounded(value, trusted).failures[0]?.looksLike;
+}
+function drawnLike(spoofed, trusted) {
+    const drawn = spoofed.map((value) => `${mask(value)} is drawn like ${lookalikeOf(value, trusted)}`);
+    return `${REFUSAL} ${drawn.join('; ')}. A character that only looks like another makes a different address, so this is not the one it resembles — ask the user which they meant instead of retrying.`;
+}
+function invented(unverified, trusted) {
+    const base = `${REFUSAL} ${masked(unverified)} does not appear anywhere in this conversation or in any tool result, so it cannot be verified. Do not guess an address.`;
+    if (!trusted.length) {
+        return `${base} Look it up first with this skill's search endpoint, or ask the user for it instead of retrying.`;
+    }
+    return `${base} Addresses that do appear: ${trusted.slice(0, HINT_LIMIT).join(', ')}. Use one of those if it is the intended target; otherwise ask the user instead of retrying.`;
+}
+function alreadyRefusedThisTurn(sources) {
+    let turnStart = 0;
+    for (const [index, source] of sources.entries()) {
+        if (source.origin === 'user')
+            turnStart = index + 1;
+    }
+    return sources
+        .slice(turnStart)
+        .some((source) => source.origin === 'tool-result' && source.text.includes(REFUSAL));
+}
+function isOutbound(toolName, args) {
+    if (!OUTBOUND_TOOLS.has(toolName))
+        return false;
+    const method = typeof args['method'] === 'string' ? args['method'] : undefined;
+    if (toolName !== 'http_request')
+        return !MCP_READ_METHOD.test(method ?? '');
+    return !READ_METHODS.has((method ?? 'GET').toUpperCase());
+}
+const IDENTIFIER_HEADER = /^\s*(message-id|in-reply-to|references)\s*:/i;
+const IDENTIFIER_FIELD = /^(message[-_]?id|in[-_]?reply[-_]?to|references)$/i;
+function addressesOutsideIdentifierHeaders(text) {
+    return text
+        .split(/\r?\n/)
+        .filter((line) => !IDENTIFIER_HEADER.test(line))
+        .flatMap((line) => line.match(ADDRESS) ?? []);
+}
+function scanPayload(payload) {
+    const found = [];
+    for (const value of strings(payload, { skip: (name) => IDENTIFIER_FIELD.test(name) })) {
+        found.push(...addressesOutsideIdentifierHeaders(value));
+        const hidden = decodeEncoded(value);
+        if (hidden !== null && printableRatio(hidden) >= PRINTABLE_RATIO) {
+            found.push(...addressesOutsideIdentifierHeaders(hidden));
+        }
+    }
+    return found;
+}
+function decodeEncoded(value) {
+    try {
+        return decodeBase64(value);
+    }
+    catch {
+        return null;
+    }
+}
+function addressesIn(sources, accept) {
+    const found = [];
+    for (const source of sources) {
+        if (!accept(source.origin))
+            continue;
+        found.push(...(source.text.match(ADDRESS) ?? []));
+    }
+    return unique(found);
+}
+function unique(values) {
+    const seen = new Map();
+    for (const value of values) {
+        if (!seen.has(key(value)))
+            seen.set(key(value), value.trim());
+    }
+    return [...seen.values()];
+}
+function key(value) {
+    return value.trim().replace(/[A-Z]/g, (upper) => upper.toLowerCase());
+}
+function isReserved(address) {
+    const domain = address.slice(address.lastIndexOf('@') + 1);
+    return RESERVED_DOMAINS.has(domain) || RESERVED_TLDS.some((tld) => domain.endsWith(`.${tld}`));
+}
+function mask(value) {
+    return value.replaceAll('@', ' [at] ');
+}
+function masked(values) {
+    return values.map(mask).join(', ');
+}

package/dist-lib/lib/tools/private-ip.d.ts

@@ -0,0 +1,4 @@
+export declare function stripIPv6Brackets(hostname: string): string;
+export declare function isPrivateIPv4(hostname: string): boolean;
+export declare function isPrivateOrBlockedIPv6(address: string): boolean;
+export declare function isPrivateOrBlocked(hostname: string): boolean;

package/dist-lib/lib/tools/private-ip.js

@@ -0,0 +1,126 @@
+export function stripIPv6Brackets(hostname) {
+    if (hostname.startsWith('[') && hostname.endsWith(']')) {
+        return hostname.slice(1, -1);
+    }
+    return hostname;
+}
+export function isPrivateIPv4(hostname) {
+    const parts = hostname.split('.').map(Number);
+    if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) {
+        return false;
+    }
+    const a = parts[0];
+    const b = parts[1];
+    if (a === undefined || b === undefined) {
+        return false;
+    }
+    return (a === 10 ||
+        a === 127 ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 169 && b === 254) ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        a === 0 ||
+        a >= 224);
+}
+export function isPrivateOrBlockedIPv6(address) {
+    const bytes = parseIPv6ToBytes(address.toLowerCase());
+    if (bytes === null) {
+        return true;
+    }
+    if (isAllZeroBytes(bytes, 0, 16)) {
+        return true;
+    }
+    if (isAllZeroBytes(bytes, 0, 15) && bytes[15] === 1) {
+        return true;
+    }
+    const embeddedIPv4 = `${bytes[12]}.${bytes[13]}.${bytes[14]}.${bytes[15]}`;
+    if (isAllZeroBytes(bytes, 0, 10) && bytes[10] === 0xff && bytes[11] === 0xff) {
+        return isPrivateIPv4(embeddedIPv4);
+    }
+    if (isAllZeroBytes(bytes, 0, 12)) {
+        return isPrivateIPv4(embeddedIPv4);
+    }
+    if ((bytes[0] & 0xfe) === 0xfc) {
+        return true;
+    }
+    if (bytes[0] === 0xfe && ((bytes[1] & 0xc0) === 0x80 || (bytes[1] & 0xc0) === 0xc0)) {
+        return true;
+    }
+    return bytes[0] === 0xff;
+}
+function parseIPv6ToBytes(lower) {
+    const zoneless = lower.split('%')[0] ?? '';
+    const compressed = zoneless.split('::');
+    if (compressed.length > 2) {
+        return null;
+    }
+    const hasCompression = compressed.length === 2;
+    const headGroups = expandEmbeddedIPv4(splitGroups(compressed[0] ?? ''));
+    const tailGroups = hasCompression ? expandEmbeddedIPv4(splitGroups(compressed[1] ?? '')) : [];
+    if (headGroups === null || tailGroups === null) {
+        return null;
+    }
+    const zeroFill = 8 - headGroups.length - tailGroups.length;
+    if (hasCompression ? zeroFill < 1 : zeroFill !== 0) {
+        return null;
+    }
+    const groups = [...headGroups, ...Array(zeroFill).fill('0'), ...tailGroups];
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 8; i++) {
+        const group = groups[i];
+        if (!/^[0-9a-f]{1,4}$/.test(group)) {
+            return null;
+        }
+        const value = Number.parseInt(group, 16);
+        bytes[i * 2] = (value >> 8) & 0xff;
+        bytes[i * 2 + 1] = value & 0xff;
+    }
+    return bytes;
+}
+function splitGroups(segment) {
+    return segment === '' ? [] : segment.split(':');
+}
+function expandEmbeddedIPv4(groups) {
+    const last = groups[groups.length - 1];
+    if (last === undefined || !last.includes('.')) {
+        return [...groups];
+    }
+    const quad = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(last);
+    if (!quad) {
+        return null;
+    }
+    const octets = quad.slice(1, 5).map(Number);
+    if (octets.some((n) => n > 255)) {
+        return null;
+    }
+    const hi = ((octets[0] << 8) | octets[1]).toString(16);
+    const lo = ((octets[2] << 8) | octets[3]).toString(16);
+    return [...groups.slice(0, -1), hi, lo];
+}
+function isAllZeroBytes(bytes, start, end) {
+    for (let i = start; i < end; i++) {
+        if (bytes[i] !== 0) {
+            return false;
+        }
+    }
+    return true;
+}
+const BLOCKED_HOSTNAMES = new Set([
+    'metadata.google.internal',
+    '169.254.169.254',
+    'metadata.azure.com'
+]);
+export function isPrivateOrBlocked(hostname) {
+    const normalized = stripIPv6Brackets(hostname).toLowerCase().replace(/\.$/, '');
+    if (BLOCKED_HOSTNAMES.has(normalized)) {
+        return true;
+    }
+    if (normalized === 'localhost' || normalized.endsWith('.localhost')) {
+        return true;
+    }
+    if (normalized.includes(':')) {
+        return isPrivateOrBlockedIPv6(normalized);
+    }
+    return isPrivateIPv4(normalized);
+}

package/dist-lib/lib/tools/rag-search.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from '../capabilities/completion.ts';
+export declare function createRagSearchTool(): ToolDefinition;

package/dist-lib/lib/tools/rag-search.js

@@ -0,0 +1,98 @@
+import { RAG_CITATION_LINE } from "../prompt.js";
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 20;
+const EXCERPT_CHARS = 1200;
+const NOT_AVAILABLE = 'rag_search is not available in this run. The current chat has no indexed knowledge base. Attach documents to the chat and try again.';
+const NO_DOCUMENTS = 'The current chat has no uploaded documents. Attach documents to the chat and try again.';
+const STILL_SYNCING = 'Attachments are still syncing and cannot be searched yet. Try again shortly.';
+const NO_RELEVANT = 'No relevant excerpts were found in the knowledge base. Answer plainly without fabricating sources.';
+export function createRagSearchTool() {
+    return {
+        name: 'rag_search',
+        toolset: 'knowledge',
+        autoApprove: true,
+        description: "Semantic search over the current chat's indexed knowledge base (uploaded documents, PDFs, notes). " +
+            'Returns ranked excerpts with source labels you can cite. Use this when the answer is fuzzy or ' +
+            'conceptual ("summarise the Q3 board notes", "what does the spec say about retries").',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Natural-language query to retrieve relevant chunks for.'
+                },
+                limit: { type: 'number', description: 'Maximum excerpts to return (1-20). Defaults to 5.' }
+            },
+            required: ['query']
+        },
+        effect: () => 'read',
+        async execute(args, ctx) {
+            const query = args.query;
+            if (typeof query !== 'string' || query.trim().length === 0) {
+                return { error: 'query must be a non-empty string' };
+            }
+            if (!ctx?.ragSearch)
+                return { content: NOT_AVAILABLE };
+            let result;
+            try {
+                result = await ctx.ragSearch({ query, limit: limitFrom(args.limit) });
+            }
+            catch (err) {
+                return { error: `rag_search failed: ${err instanceof Error ? err.message : String(err)}` };
+            }
+            if (!result.enabled)
+                return { content: NOT_AVAILABLE };
+            if (result.errorMessage)
+                return { error: `rag_search failed: ${result.errorMessage}` };
+            if (result.hits.length === 0) {
+                if (!result.hasKnowledge)
+                    return { content: NO_DOCUMENTS };
+                if (result.indexEmpty || result.pendingReferenced)
+                    return { content: STILL_SYNCING };
+                return { content: NO_RELEVANT };
+            }
+            return { content: formatHits(result.hits) };
+        }
+    };
+}
+function limitFrom(raw) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw))
+        return DEFAULT_LIMIT;
+    return Math.min(MAX_LIMIT, Math.max(1, Math.floor(raw)));
+}
+function formatHits(hits) {
+    const blocks = hits
+        .map((hit, index) => `${labelFor(hit, index)}\n${truncate(hit.content.trim())}`)
+        .join('\n\n');
+    return `${blocks}\n\n${RAG_CITATION_LINE}`;
+}
+function labelFor(hit, index) {
+    const metadata = parseMetadata(hit.metadataJson);
+    const title = metadata.title ?? 'document';
+    const chunk = metadata.chunkIndex ?? index;
+    return `[Source ${index + 1}: ${title}, chunk ${chunk}, score ${hit.score.toFixed(3)}]`;
+}
+function parseMetadata(raw) {
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return {};
+        return {
+            title: 'title' in parsed && typeof parsed.title === 'string' ? parsed.title : undefined,
+            chunkIndex: 'chunkIndex' in parsed &&
+                typeof parsed.chunkIndex === 'number' &&
+                Number.isSafeInteger(parsed.chunkIndex) &&
+                parsed.chunkIndex >= 0
+                ? parsed.chunkIndex
+                : undefined
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function truncate(text) {
+    return text.length <= EXCERPT_CHARS ? text : `${text.slice(0, EXCERPT_CHARS)}…`;
+}

package/dist-lib/lib/tools/read-files.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDefinition } from '../capabilities/completion.ts';
+import { type FsToolOptions } from './fs/scope.ts';
+export declare const DEFAULT_READ_CHARS = 8192;
+export declare const MAX_READ_CHARS = 65536;
+export declare function createReadFilesTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;