@qvac/harness 0.3.3 → 0.5.0

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

@@ -32,8 +32,9 @@ function operationTool(owningSkill, operation, transportTool) {
         async execute(args, ctx) {
             const skillContext = { ...ctx, skills: [owningSkill] };
             const built = builder.build(args);
-            if ('error' in built)
+            if ('error' in built) {
                 return { error: `${operation.tool}: ${built.error}` };
+            }
             if (read && (built.request.body !== undefined || built.request.encode !== undefined)) {
                 return { error: `${operation.tool}: a read operation cannot send a body` };
             }
@@ -42,8 +43,9 @@ function operationTool(owningSkill, operation, transportTool) {
                 return transportTool.execute({ url: request.url, method: request.method, params: built.request.params }, skillContext);
             }
             const url = fillTemplate(request.url, args, request.urlDefaults);
-            if ('error' in url)
+            if ('error' in url) {
                 return { error: `${operation.tool}: ${url.error}` };
+            }
             const { response } = operation;
             const result = await transportTool.execute({
                 url: url.value,
@@ -59,20 +61,24 @@ function operationTool(owningSkill, operation, transportTool) {
 const JsonResult = z.looseObject({ status: z.number().optional(), body: z.string() });
 function capBody(result) {
     const parsed = JsonResult.safeParse(result);
-    if (!parsed.success)
+    if (!parsed.success) {
         return result;
+    }
     return { ...parsed.data, body: truncateResponseBody(parsed.data.body) };
 }
 function shapeResponse(result, response) {
     const parsed = JsonResult.safeParse(result);
-    if (!parsed.success)
+    if (!parsed.success) {
         return result;
+    }
     const { status } = parsed.data;
-    if (status !== undefined && status >= 400)
+    if (status !== undefined && status >= 400) {
         return result;
+    }
     const body = jsonObject(parsed.data.body);
-    if (!body)
+    if (!body) {
         return result;
+    }
     const shaped = 'pick' in response ? pick(body, response.pick) : DECODERS[response.decode].decode(body);
     return { ...parsed.data, body: JSON.stringify(shaped) };
 }
@@ -87,9 +93,11 @@ function jsonObject(body) {
 }
 function pick(body, keys) {
     const picked = {};
-    for (const key of keys)
-        if (key in body)
+    for (const key of keys) {
+        if (key in body) {
             picked[key] = body[key];
+        }
+    }
     return picked;
 }
 const PLACEHOLDER = /\{(\w+)\}/g;
@@ -97,12 +105,14 @@ function fillTemplate(template, args, defaults) {
     const missing = [];
     const value = template.replace(PLACEHOLDER, (_match, name) => {
         const filled = args[name] ?? defaults?.[name];
-        if (filled === undefined)
+        if (filled === undefined) {
             missing.push(name);
+        }
         return encodeURIComponent(String(filled));
     });
-    if (missing.length)
+    if (missing.length) {
         return { error: `missing required argument ${missing.join(', ')}` };
+    }
     return { value };
 }
 function hostOf(url) {

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

@@ -23,8 +23,9 @@ const MessageSchema = z.object({
 const gmailMessage = {
     decode(body) {
         const parsed = MessageSchema.safeParse(body);
-        if (!parsed.success)
+        if (!parsed.success) {
             return body;
+        }
         const { id, threadId, labelIds, snippet, payload } = parsed.data;
         return {
             id,
@@ -40,27 +41,32 @@ function keptHeaders(part) {
     const kept = {};
     for (const header of part.headers ?? []) {
         const name = KEPT_HEADERS.find((known) => known.toLowerCase() === header.name.toLowerCase());
-        if (name && !(name in kept))
+        if (name && !(name in kept)) {
             kept[name] = header.value;
+        }
     }
     return kept;
 }
 function textOf(part) {
     const plain = leaves(part, 'text/plain');
-    if (plain.length)
+    if (plain.length) {
         return plain.join('\n\n');
+    }
     const html = leaves(part, 'text/html')
         .map((leaf) => extractPageText(leaf).text)
         .filter((text) => text.length > 0);
-    if (html.length)
+    if (html.length) {
         return html.join('\n\n');
+    }
     return undefined;
 }
 function leaves(part, mimeType) {
-    if (part.parts?.length)
+    if (part.parts?.length) {
         return part.parts.flatMap((child) => leaves(child, mimeType));
-    if (part.mimeType?.toLowerCase() !== mimeType || part.filename || !part.body?.data)
+    }
+    if (part.mimeType?.toLowerCase() !== mimeType || part.filename || !part.body?.data) {
         return [];
+    }
     const text = decodeData(part.body.data);
     return text ? [text] : [];
 }

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

@@ -14,7 +14,7 @@ export const GmailEnvelopeSchema = z
     inReplyTo: z.string().optional(),
     references: z.string().optional()
 })
-    .refine((value) => Boolean(value.text?.length) || Boolean(value.html?.length));
+    .refine((value) => !!value.text?.length || !!value.html?.length);
 export function buildGmailMessage(envelope) {
     return [...headerLines(envelope), ...bodyLines(envelope)].join('\r\n');
 }
@@ -31,8 +31,9 @@ function joinAddresses(value) {
 }
 function encodeHeaderValue(value) {
     const sanitized = stripNewlines(value);
-    if (/^[\x20-\x7e]*$/.test(sanitized))
+    if (/^[\x20-\x7e]*$/.test(sanitized)) {
         return sanitized;
+    }
     return `=?UTF-8?B?${b4a.toString(b4a.from(sanitized, 'utf8'), 'base64')}?=`;
 }
 function headerLines(envelope) {

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

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

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

@@ -9,20 +9,22 @@ 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 } = {}) {
+export function guardToolCall(toolName, args, { sources, externalWrite = false }) {
     if (!externalWrite && !isOutbound(toolName, args))
         return null;
     const addresses = unique(scanPayload(args));
-    if (!addresses.length)
+    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)
+    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.`;
     }
@@ -32,8 +34,9 @@ export function guardToolCall(toolName, args, sources, { externalWrite = false }
         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)
+    if (spoofed.length) {
         return drawnLike(spoofed, trusted);
+    }
     return invented(unverified, trusted);
 }
 function lookalikeOf(value, trusted) {
@@ -53,8 +56,9 @@ function invented(unverified, trusted) {
 function alreadyRefusedThisTurn(sources) {
     let turnStart = 0;
     for (const [index, source] of sources.entries()) {
-        if (source.origin === 'user')
+        if (source.origin === 'user') {
             turnStart = index + 1;
+        }
     }
     return sources
         .slice(turnStart)
@@ -63,9 +67,10 @@ function alreadyRefusedThisTurn(sources) {
 function isOutbound(toolName, args) {
     if (!OUTBOUND_TOOLS.has(toolName))
         return false;
-    const method = typeof args['method'] === 'string' ? args['method'] : undefined;
-    if (toolName !== 'http_request')
+    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;
@@ -107,8 +112,9 @@ function addressesIn(sources, accept) {
 function unique(values) {
     const seen = new Map();
     for (const value of values) {
-        if (!seen.has(key(value)))
+        if (!seen.has(key(value))) {
             seen.set(key(value), value.trim());
+        }
     }
     return [...seen.values()];
 }

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

@@ -41,13 +41,14 @@ export function isPrivateOrBlockedIPv6(address) {
     if (isAllZeroBytes(bytes, 0, 12)) {
         return isPrivateIPv4(embeddedIPv4);
     }
-    if ((bytes[0] & 0xfe) === 0xfc) {
+    const [first = 0, second = 0] = bytes;
+    if ((first & 0xfe) === 0xfc) {
         return true;
     }
-    if (bytes[0] === 0xfe && ((bytes[1] & 0xc0) === 0x80 || (bytes[1] & 0xc0) === 0xc0)) {
+    if (first === 0xfe && ((second & 0xc0) === 0x80 || (second & 0xc0) === 0xc0)) {
         return true;
     }
-    return bytes[0] === 0xff;
+    return first === 0xff;
 }
 function parseIPv6ToBytes(lower) {
     const zoneless = lower.split('%')[0] ?? '';
@@ -67,8 +68,7 @@ function parseIPv6ToBytes(lower) {
     }
     const groups = [...headGroups, ...Array(zeroFill).fill('0'), ...tailGroups];
     const bytes = new Uint8Array(16);
-    for (let i = 0; i < 8; i++) {
-        const group = groups[i];
+    for (const [i, group] of groups.entries()) {
         if (!/^[0-9a-f]{1,4}$/.test(group)) {
             return null;
         }
@@ -94,8 +94,9 @@ function expandEmbeddedIPv4(groups) {
     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);
+    const [a = 0, b = 0, c = 0, d = 0] = octets;
+    const hi = ((a << 8) | b).toString(16);
+    const lo = ((c << 8) | d).toString(16);
     return [...groups.slice(0, -1), hi, lo];
 }
 function isAllZeroBytes(bytes, start, end) {

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

@@ -1,3 +1,4 @@
+import { errorMessage } from '../guards.js';
 import { RAG_CITATION_LINE } from '../prompt.js';
 const DEFAULT_LIMIT = 5;
 const MAX_LIMIT = 20;
@@ -31,24 +32,29 @@ export function createRagSearchTool() {
             if (typeof query !== 'string' || query.trim().length === 0) {
                 return { error: 'query must be a non-empty string' };
             }
-            if (!ctx?.ragSearch)
+            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)}` };
+                return { error: `rag_search failed: ${errorMessage(err)}` };
             }
-            if (!result.enabled)
+            if (!result.enabled) {
                 return { content: NOT_AVAILABLE };
-            if (result.errorMessage)
+            }
+            if (result.errorMessage) {
                 return { error: `rag_search failed: ${result.errorMessage}` };
+            }
             if (result.hits.length === 0) {
-                if (!result.hasKnowledge)
+                if (!result.hasKnowledge) {
                     return { content: NO_DOCUMENTS };
-                if (result.indexEmpty || result.pendingReferenced)
+                }
+                if (result.indexEmpty || result.pendingReferenced) {
                     return { content: STILL_SYNCING };
+                }
                 return { content: NO_RELEVANT };
             }
             return { content: formatHits(result.hits) };
@@ -77,8 +83,9 @@ function parseMetadata(raw) {
         return {};
     try {
         const parsed = JSON.parse(raw);
-        if (typeof parsed !== 'object' || parsed === null)
+        if (typeof parsed !== 'object' || parsed === null) {
             return {};
+        }
         return {
             title: 'title' in parsed && typeof parsed.title === 'string' ? parsed.title : undefined,
             chunkIndex: 'chunkIndex' in parsed &&

package/dist-lib/lib/tools/read-files.js

@@ -1,3 +1,4 @@
+import { errorMessage, isRecord } from '../guards.js';
 import { readLines } from './fs/read.js';
 import { isDriveReadTruncated } from './fs/remote.js';
 import { canonicalDenyRoots, defaultRealpath, resolveKey } from './fs/scope.js';
@@ -7,8 +8,9 @@ function lineIndex(value) {
     if (value === undefined || value === null)
         return undefined;
     const n = Number(value);
-    if (!Number.isInteger(n) || n < 1)
+    if (!Number.isInteger(n) || n < 1) {
         return null;
+    }
     return n;
 }
 function fileRequests(raw) {
@@ -16,22 +18,19 @@ function fileRequests(raw) {
         return null;
     const files = [];
     for (const entry of raw) {
-        const record = entry;
-        if (typeof record?.path !== 'string' || !record.path.trim())
+        if (!isRecord(entry) || typeof entry.path !== 'string' || !entry.path.trim()) {
             return null;
-        const startLine = lineIndex(record.startLine);
-        const endLine = lineIndex(record.endLine);
-        if (startLine === null || endLine === null)
+        }
+        const startLine = lineIndex(entry.startLine);
+        const endLine = lineIndex(entry.endLine);
+        if (startLine === null || endLine === null) {
             return null;
-        files.push({
-            path: record.path,
-            ...(startLine !== undefined ? { startLine } : {}),
-            ...(endLine !== undefined ? { endLine } : {})
-        });
+        }
+        files.push({ path: entry.path, startLine, endLine });
     }
     return files;
 }
-async function slice(drive, key, request, maxChars) {
+async function slice(drive, key, { request, maxChars }) {
     const first = request.startLine ?? 1;
     const last = request.endLine ?? Infinity;
     const kept = [];
@@ -46,13 +45,15 @@ async function slice(drive, key, request, maxChars) {
                 break;
             kept.push(line);
             length += line.length + (kept.length > 1 ? 1 : 0);
-            if (length > maxChars)
+            if (length > maxChars) {
                 break;
+            }
         }
     }
     catch (err) {
-        if (!isDriveReadTruncated(err))
+        if (!isDriveReadTruncated(err)) {
             throw err;
+        }
         capped = true;
     }
     const text = kept.join('\n');
@@ -107,8 +108,9 @@ export function createReadFilesTool({ realpath = defaultRealpath, deniedRoots }
         },
         resource(args) {
             const files = fileRequests(args.files);
-            if (!files)
+            if (!files) {
                 return null;
+            }
             const label = files
                 .map((f) => f.path)
                 .slice(0, 3)
@@ -121,14 +123,15 @@ export function createReadFilesTool({ realpath = defaultRealpath, deniedRoots }
         async execute(rawArgs, ctx) {
             const roots = ctx?.fsRoots ?? [];
             const requests = fileRequests(rawArgs.files);
-            if (!requests)
+            if (!requests) {
                 return { error: 'files must be a non-empty array of { path }' };
+            }
             const maxChars = rawArgs.maxChars ? Number(rawArgs.maxChars) : DEFAULT_READ_CHARS;
             const files = [];
             const failed = [];
             const deny = await canonicalDenyRoots(deniedRoots, realpath);
             for (const request of requests) {
-                const resolved = await resolveKey(request.path, roots, realpath, deny);
+                const resolved = await resolveKey(request.path, roots, { realpath, deny });
                 if ('error' in resolved) {
                     failed.push({ path: request.path, error: resolved.error });
                     continue;
@@ -140,14 +143,14 @@ export function createReadFilesTool({ realpath = defaultRealpath, deniedRoots }
                     }
                     files.push({
                         path: request.path,
-                        ...(await slice(resolved.root.drive, resolved.key, request, maxChars))
+                        ...(await slice(resolved.root.drive, resolved.key, { request, maxChars }))
                     });
                 }
                 catch (err) {
-                    failed.push({ path: request.path, error: err.message });
+                    failed.push({ path: request.path, error: errorMessage(err) });
                 }
             }
-            return { files, ...(failed.length ? { failed } : {}) };
+            return { files, failed: failed.length ? failed : undefined };
         }
     };
 }

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

@@ -40,8 +40,9 @@ function toolNote(tools) {
     const grants = [];
     for (const entry of tools) {
         const { name } = parseToolGrant(entry);
-        if (!grants.includes(name))
+        if (!grants.includes(name)) {
             grants.push(name);
+        }
     }
     return [
         `You can now call: ${grants.join(', ')}.`,
@@ -49,17 +50,21 @@ function toolNote(tools) {
             'anything, open another app, or run code themselves.'
     ].join(' ');
 }
+async function addSkillFiles(files, drive, name) {
+    for await (const entry of drive.list(`/${name}`)) {
+        const rel = String(entry.key).slice(name.length + 2);
+        if (rel && rel !== 'SKILL.md') {
+            files.add(rel);
+        }
+    }
+}
 async function listSkillFiles(drives, name) {
     const files = new Set();
     for (const drive of drives) {
         if (!drive)
             continue;
         try {
-            for await (const entry of drive.list(`/${name}`)) {
-                const rel = String(entry.key).slice(name.length + 2);
-                if (rel && rel !== 'SKILL.md')
-                    files.add(rel);
-            }
+            await addSkillFiles(files, drive, name);
         }
         catch {
         }
@@ -75,23 +80,26 @@ async function vaultModeNote(name, credentialStore, ctx) {
         return null;
     const record = credentialRecord(await credentialStore(OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY, { ...ctx, skills: [name] }));
     const token = record?.token?.trim();
-    if (!token || !isObsidianVaultPath(token))
+    if (!token || !isObsidianVaultPath(token)) {
         return null;
+    }
     return OBSIDIAN_VAULT_MODE_NOTE;
 }
 export function createSkillTool({ skillsDir, overlayDir = resolveSkillsOverlayDir(), read, credentialStore } = {}) {
     const baseDrive = skillsDir ? new Localdrive(skillsDir) : null;
     const overlayDrive = overlayDir ? new Localdrive(overlayDir) : null;
     async function resolveSkill(name, file) {
-        if (read)
+        if (read) {
             return { raw: await read(name, file), root: skillsDir };
+        }
         for (const [drive, root] of [
             [overlayDrive, overlayDir],
             [baseDrive, skillsDir]
         ]) {
             const buf = drive ? await drive.get(`/${name}/${file}`) : null;
-            if (buf)
+            if (buf) {
                 return { raw: b4a.toString(buf, 'utf8'), root: root ?? undefined };
+            }
         }
         throw new Error(`ENOENT: ${name}/${file}`);
     }
@@ -154,8 +162,9 @@ export function createSkillTool({ skillsDir, overlayDir = resolveSkillsOverlayDi
                 return await load(file);
             }
             catch {
-                if (file === MAIN_FILE)
+                if (file === MAIN_FILE) {
                     return { error: `skill not found: ${name}` };
+                }
                 const available = await listSkillFiles([overlayDrive, baseDrive], name);
                 const near = nearestFile(file, available);
                 if (near !== null) {

package/dist-lib/lib/tools/skills/auth-resolver.d.ts

@@ -1,6 +1,6 @@
 import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
 import type { ToolExecuteContext } from '../../capabilities/completion.ts';
-import { type ParseResult } from '../http-request/utils.ts';
+import { type ParseResult } from '../http-request/request.ts';
 export interface HttpRequestAuth {
     type: 'bearer';
     tokenCredentialKey: string;
@@ -17,28 +17,21 @@ export type CredentialAllowList = Record<string, string | string[]>;
 export declare function urlAllowed(url: URL, patterns: readonly string[]): boolean;
 export declare function isCredentialUrlAllowed(target: string, patterns: readonly string[]): boolean;
 export type CredentialAllowListFn = (ctx?: ToolExecuteContext) => CredentialAllowList;
-export type AuthOutcome = {
+export interface ResolvedCredential {
     readonly token: string;
     readonly key: string;
-} | {
+}
+export interface AuthError {
     readonly error: string;
-};
+}
+export type AuthOutcome = ResolvedCredential | AuthError;
 export declare function parseAuth(v: unknown): ParseResult<HttpRequestAuth>;
 export declare function resolveAuth(auth: HttpRequestAuth, url: URL, credentialStore: CredentialStoreFn | undefined, credentialAllowList: CredentialAllowList | undefined, ctx: ToolExecuteContext | undefined): Promise<AuthOutcome>;
-export declare function resolveAutoAuth(url: URL, credentialStore: CredentialStoreFn | undefined, credentialAllowList: CredentialAllowList | undefined, ctx: ToolExecuteContext | undefined): Promise<{
-    token: string;
-    key: string;
-} | {
-    error: string;
-} | null>;
-export type BearerOutcome = {
+export declare function resolveAutoAuth(url: URL, credentialStore: CredentialStoreFn | undefined, credentialAllowList: CredentialAllowList | undefined, ctx: ToolExecuteContext | undefined): Promise<AuthOutcome | null>;
+export interface BearerHeader {
     readonly header: string | null;
     readonly credentialKey?: string;
-} | {
-    readonly error: string;
-};
+}
+export type BearerOutcome = BearerHeader | AuthError;
 export declare function resolveBearerHeader(auth: HttpRequestAuth | undefined, url: URL, credentialStore: CredentialStoreFn | undefined, credentialAllowList: CredentialAllowList | undefined, ctx: ToolExecuteContext | undefined, signal: BareAbortSignal): Promise<BearerOutcome>;
-export declare function resolveRedirectBearerHeader(auth: HttpRequestAuth | undefined, url: URL, credentialStore: CredentialStoreFn | undefined, credentialAllowList: CredentialAllowList | undefined, ctx: ToolExecuteContext | undefined, signal: BareAbortSignal): Promise<{
-    readonly header: string | null;
-    readonly credentialKey?: string;
-}>;
+export declare function resolveRedirectBearerHeader(auth: HttpRequestAuth | undefined, url: URL, credentialStore: CredentialStoreFn | undefined, credentialAllowList: CredentialAllowList | undefined, ctx: ToolExecuteContext | undefined, signal: BareAbortSignal): Promise<BearerHeader>;