@qvac/harness 0.0.0 → 0.1.1

package/dist-lib/lib/tools/http-request/encode-fields.d.ts

@@ -0,0 +1,2 @@
+export type FieldEncoding = 'base64' | 'base64url';
+export declare function encodeDeclaredFields(body: string | Record<string, unknown> | undefined, encode: Record<string, unknown> | undefined): string | Record<string, unknown> | undefined;

package/dist-lib/lib/tools/http-request/encode-fields.js

@@ -0,0 +1,69 @@
+const BASE64URL = /^[A-Za-z0-9_-]+={0,2}$/;
+const PRINTABLE_RATIO = 0.9;
+export function encodeDeclaredFields(body, encode) {
+    if (!encode)
+        return body;
+    const parsed = asObject(body);
+    if (!parsed)
+        return body;
+    let next = parsed;
+    for (const [path, encoding] of Object.entries(encode)) {
+        if (encoding !== 'base64' && encoding !== 'base64url')
+            continue;
+        next = setAt(next, path.split('.'), encoding);
+    }
+    return next;
+}
+function asObject(body) {
+    if (typeof body === 'string') {
+        try {
+            return asObject(JSON.parse(body));
+        }
+        catch {
+            return null;
+        }
+    }
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        return null;
+    return body;
+}
+function setAt(body, path, encoding) {
+    const [head, ...rest] = path;
+    if (head === undefined)
+        return body;
+    const current = body[head];
+    if (rest.length) {
+        if (typeof current !== 'object' || current === null)
+            return body;
+        return { ...body, [head]: setAt(current, rest, encoding) };
+    }
+    if (typeof current !== 'string')
+        return body;
+    return { ...body, [head]: encodeValue(current, encoding) };
+}
+function encodeValue(value, encoding) {
+    if (isAlreadyEncoded(value))
+        return value;
+    return Buffer.from(value, 'utf8').toString(encoding);
+}
+function isAlreadyEncoded(value) {
+    if (!BASE64URL.test(value) && !/^[A-Za-z0-9+/]+={0,2}$/.test(value))
+        return false;
+    try {
+        const decoded = Buffer.from(value, 'base64').toString('utf8');
+        return decoded.length > 0 && isMostlyPrintable(decoded);
+    }
+    catch {
+        return false;
+    }
+}
+function isMostlyPrintable(text) {
+    const chars = [...text];
+    const printable = chars.filter((char) => {
+        const code = char.codePointAt(0) ?? 0;
+        if (code === 0xfffd)
+            return false;
+        return code === 9 || code === 10 || code === 13 || (code >= 32 && code !== 127);
+    }).length;
+    return printable / chars.length >= PRINTABLE_RATIO;
+}

package/dist-lib/lib/tools/http-request/truncate-response.d.ts

@@ -0,0 +1 @@
+export declare function truncateResponseBody(body: string): string;

package/dist-lib/lib/tools/http-request/truncate-response.js

@@ -0,0 +1,83 @@
+import { MAX_RESPONSE_CHARS } from "./utils.js";
+export function truncateResponseBody(body) {
+    if (body.length <= MAX_RESPONSE_CHARS)
+        return body;
+    return fitJson(body) ?? `${body.slice(0, MAX_RESPONSE_CHARS)}… [truncated]`;
+}
+function fitJson(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    return JSON.stringify(fit(parsed, MAX_RESPONSE_CHARS));
+}
+const MARKER_CHARS = 64;
+function shrinkable(value) {
+    if (typeof value === 'string')
+        return true;
+    return typeof value === 'object' && value !== null;
+}
+const ELISION = '… [truncated]';
+function fitString(value, budget) {
+    const room = budget - ELISION.length - 2;
+    if (room <= 0)
+        return ELISION;
+    return `${value.slice(0, room)}${ELISION}`;
+}
+function fit(value, budget) {
+    const room = budget - MARKER_CHARS;
+    if (Array.isArray(value)) {
+        const kept = [];
+        let used = 2;
+        for (const item of value) {
+            const size = JSON.stringify(item).length + 1;
+            if (used + size > room) {
+                const left = room - used;
+                if (left > MARKER_CHARS && shrinkable(item))
+                    kept.push(fit(item, left));
+                break;
+            }
+            kept.push(item);
+            used += size;
+        }
+        const dropped = value.length - kept.length;
+        if (dropped > 0)
+            kept.push(`… [${dropped} more items truncated]`);
+        return kept;
+    }
+    if (typeof value === 'object' && value !== null) {
+        const entries = Object.entries(value);
+        const out = {};
+        let used = 2;
+        let kept = 0;
+        let refitted = false;
+        for (const [key, item] of entries) {
+            const keySize = JSON.stringify(key).length + 2;
+            const size = keySize + JSON.stringify(item).length;
+            if (used + size > room) {
+                const left = room - used - keySize;
+                if (!refitted && left > MARKER_CHARS && shrinkable(item)) {
+                    const shrunk = fit(item, left);
+                    out[key] = shrunk;
+                    used += keySize + JSON.stringify(shrunk).length;
+                    refitted = true;
+                    kept++;
+                }
+                continue;
+            }
+            out[key] = item;
+            used += size;
+            kept++;
+        }
+        if (kept < entries.length)
+            out['…'] = `[${entries.length - kept} more fields truncated]`;
+        return out;
+    }
+    if (typeof value === 'string' && JSON.stringify(value).length > budget) {
+        return fitString(value, budget);
+    }
+    return value;
+}

package/dist-lib/lib/tools/http-request/utils.d.ts

@@ -0,0 +1,27 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+export declare const MAX_RESPONSE_CHARS = 8192;
+export declare const TIMEOUT_MS = 10000;
+export interface FetchInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal: BareAbortSignal;
+    redirect?: 'manual';
+    validatedAddresses?: readonly string[] | undefined;
+    maxBytes?: number;
+    truncate?: boolean;
+}
+export declare function isRedirectStatus(status: number): boolean;
+export type ParseResult<T> = {
+    readonly ok: true;
+    readonly value: T | undefined;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export declare function parseObjectArg(v: unknown, name: string): ParseResult<Record<string, unknown>>;
+export declare function parseJsonBody(body: string | Record<string, unknown> | undefined, contentType?: string): ParseResult<string | Record<string, unknown>>;
+export declare function applyQuery(url: URL, query: Record<string, unknown>): void;
+export declare function contentTypeOf(headers: unknown): string | undefined;
+export declare function buildHeaders(headerArgs: Record<string, unknown>): Record<string, string>;
+export declare function encodeBody(body: string | Record<string, unknown> | undefined, headers: Record<string, string>): string | undefined;

package/dist-lib/lib/tools/http-request/utils.js

@@ -0,0 +1,84 @@
+const BLOCKED_HEADERS = new Set(['authorization', 'cookie', 'proxy-authorization']);
+export const MAX_RESPONSE_CHARS = 8192;
+export const TIMEOUT_MS = 10_000;
+export function isRedirectStatus(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+export function parseObjectArg(v, name) {
+    if (v === null || v === undefined)
+        return { ok: true, value: undefined };
+    let value = v;
+    if (typeof v === 'string') {
+        try {
+            value = JSON.parse(v);
+        }
+        catch {
+            return { ok: false, error: `${name} must be an object` };
+        }
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return { ok: false, error: `${name} must be an object` };
+    }
+    return { ok: true, value: value };
+}
+const BODY_JSON_ERROR = 'body is not valid JSON — resend it as one complete JSON object';
+export function parseJsonBody(body, contentType) {
+    if (typeof body !== 'string')
+        return { ok: true, value: body };
+    if (contentType !== undefined && !/json/i.test(contentType))
+        return { ok: true, value: body };
+    const text = body.trim();
+    if (text[0] !== '{' && text[0] !== '[')
+        return { ok: true, value: body };
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, error: BODY_JSON_ERROR };
+    }
+    return { ok: true, value: isPlainRecord(parsed) ? parsed : body };
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function applyQuery(url, query) {
+    for (const [key, value] of Object.entries(query)) {
+        if (value === null || value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                url.searchParams.append(key, String(item));
+        }
+        else {
+            url.searchParams.append(key, String(value));
+        }
+    }
+}
+export function contentTypeOf(headers) {
+    if (typeof headers !== 'object' || headers === null)
+        return undefined;
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === 'content-type')
+            return String(value);
+    }
+    return undefined;
+}
+export function buildHeaders(headerArgs) {
+    const headers = {};
+    for (const [key, value] of Object.entries(headerArgs)) {
+        if (!BLOCKED_HEADERS.has(key.toLowerCase()))
+            headers[key] = String(value);
+    }
+    return headers;
+}
+export function encodeBody(body, headers) {
+    if (body === null || body === undefined)
+        return undefined;
+    if (typeof body !== 'object')
+        return String(body);
+    if (!Object.keys(headers).some((h) => h.toLowerCase() === 'content-type')) {
+        headers['Content-Type'] = 'application/json';
+    }
+    return JSON.stringify(body);
+}

package/dist-lib/lib/tools/http-request.d.ts

@@ -0,0 +1,20 @@
+import type { ToolDefinition } from '../capabilities/completion.ts';
+import { type FetchInit } from './http-request/utils.ts';
+import { type CredentialAllowListFn, type CredentialStoreFn } from './skills/auth-resolver.ts';
+import { type HostResolver } from './url-guard.ts';
+export type FetchFn = (url: URL, init: FetchInit) => Promise<{
+    status: number;
+    headers?: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string> | string;
+    bytes?(): Promise<Uint8Array> | Uint8Array;
+}>;
+export type { CredentialAllowList, CredentialAllowListFn, CredentialRecord, CredentialStoreFn, CredentialStoreValue } from './skills/auth-resolver.ts';
+export interface HttpRequestToolOptions {
+    fetch?: FetchFn;
+    credentialStore?: CredentialStoreFn;
+    credentialAllowList?: CredentialAllowListFn;
+    resolveHost?: HostResolver;
+}
+export declare function createHttpRequestTool({ fetch: fetchImpl, credentialStore, credentialAllowList, resolveHost }?: HttpRequestToolOptions): ToolDefinition;

package/dist-lib/lib/tools/http-request.js

@@ -0,0 +1,177 @@
+import defaultFetch from '#no-redirect-fetch';
+import { AbortController } from 'bare-abort-controller';
+import { lookupHost } from "../dns-lookup.js";
+import { READ_METHODS } from "./http-methods.js";
+import { encodeDeclaredFields } from "./http-request/encode-fields.js";
+import { truncateResponseBody } from "./http-request/truncate-response.js";
+import { AbortedError } from "../helpers/race-abort.js";
+import { applyQuery, buildHeaders, contentTypeOf, encodeBody, isRedirectStatus, parseJsonBody, parseObjectArg, TIMEOUT_MS } from "./http-request/utils.js";
+import { parseAuth, resolveBearerHeader, resolveRedirectBearerHeader } from "./skills/auth-resolver.js";
+import { recordCredentialHealth } from "./skills/credential-health.js";
+import { resolveOutboundUrl } from "./url-guard.js";
+const MAX_REDIRECTS = 5;
+export function createHttpRequestTool({ fetch: fetchImpl, credentialStore, credentialAllowList, resolveHost = lookupHost } = {}) {
+    return {
+        name: 'http_request',
+        toolset: 'http-request',
+        description: 'Make an outbound HTTP or HTTPS request and return the response status and body (truncated). Authorization/Cookie headers are stripped before sending. Stored skill credentials are attached automatically for their allow-listed hosts; `auth` is only needed to force a specific credential key.',
+        parameters: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'Full http:// or https:// URL' },
+                method: {
+                    type: 'string',
+                    enum: ['GET', 'POST', 'PUT', 'DELETE'],
+                    description: 'Defaults to GET'
+                },
+                headers: { type: 'object', description: 'Optional request headers' },
+                query: {
+                    type: 'object',
+                    description: 'Optional query params appended to the URL. Array values append repeated keys.'
+                },
+                body: {
+                    type: 'object',
+                    description: 'Request body, as a JSON object or a string. Objects are JSON-encoded and sent as application/json unless you set Content-Type yourself.'
+                },
+                encode: {
+                    type: 'object',
+                    description: 'Optional. Body fields to base64-encode before sending, as {"<dotted.path>": "base64url"}. Pass the field as plain text — never encode it yourself.'
+                },
+                auth: {
+                    type: 'object',
+                    description: 'Optional bearer auth: {"type": "bearer", "tokenCredentialKey": "<key>"}. Pass ONLY the credential key name — NEVER a token value. The tool resolves the actual secret itself; the model never sees it.'
+                }
+            },
+            required: ['url']
+        },
+        autoApprove: false,
+        effect(args) {
+            const method = typeof args.method === 'string' ? args.method.toUpperCase() : undefined;
+            if (method === undefined || !READ_METHODS.has(method))
+                return 'write';
+            return args.body === undefined && args.encode === undefined ? 'read' : 'write';
+        },
+        resource(args) {
+            try {
+                return { kind: 'host', label: new URL(String(args.url)).hostname };
+            }
+            catch {
+                return null;
+            }
+        },
+        async execute(rawArgs, ctx) {
+            const args = rawArgs;
+            let url;
+            try {
+                url = new URL(args.url);
+            }
+            catch {
+                return { error: `invalid URL: ${args.url}` };
+            }
+            if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+                return { error: `unsupported protocol: ${url.protocol}` };
+            }
+            const query = parseObjectArg(args.query, 'query');
+            if (!query.ok)
+                return { error: query.error };
+            const encodeArgs = parseObjectArg(args.encode, 'encode');
+            if (!encodeArgs.ok)
+                return { error: encodeArgs.error };
+            const headerArgs = parseObjectArg(args.headers, 'headers');
+            if (!headerArgs.ok)
+                return { error: headerArgs.error };
+            const headers = headerArgs.value ? buildHeaders(headerArgs.value) : {};
+            const parsedBody = parseJsonBody(args.body, contentTypeOf(headers));
+            if (!parsedBody.ok)
+                return { error: parsedBody.error };
+            if (query.value)
+                applyQuery(url, query.value);
+            const auth = parseAuth(args.auth);
+            if (!auth.ok)
+                return { error: auth.error };
+            const allowList = credentialAllowList?.(ctx);
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(undefined), TIMEOUT_MS);
+            try {
+                const initialCheck = await resolveOutboundUrl(url, resolveHost, controller.signal);
+                if (initialCheck.blocked)
+                    return { error: initialCheck.blocked };
+                const bearer = await resolveBearerHeader(auth.value, url, credentialStore, allowList, ctx, controller.signal);
+                if ('error' in bearer)
+                    return { error: bearer.error };
+                const redirectAuth = bearer.credentialKey
+                    ? { type: 'bearer', tokenCredentialKey: bearer.credentialKey }
+                    : undefined;
+                const encoded = encodeDeclaredFields(parsedBody.value, encodeArgs.value);
+                const requestBody = encodeBody(encoded, headers);
+                const fetch = fetchImpl ?? defaultFetch;
+                let currentUrl = url;
+                let method = args.method ?? 'GET';
+                let body = requestBody;
+                let header = bearer.header;
+                let credentialKey = bearer.credentialKey;
+                let validatedAddresses = initialCheck.addresses;
+                let response;
+                for (let redirects = 0;; redirects++) {
+                    const hopHeaders = { ...headers };
+                    delete hopHeaders['Authorization'];
+                    if (header)
+                        hopHeaders['Authorization'] = header;
+                    response = await fetch(currentUrl, {
+                        method,
+                        headers: hopHeaders,
+                        body,
+                        signal: controller.signal,
+                        redirect: 'manual',
+                        validatedAddresses
+                    });
+                    if (credentialKey) {
+                        recordCredentialHealth(credentialKey, response.status, ctx?.agentId);
+                    }
+                    if (!isRedirectStatus(response.status))
+                        break;
+                    const location = response.headers?.get('location');
+                    if (!location)
+                        break;
+                    let nextUrl;
+                    try {
+                        nextUrl = new URL(location, currentUrl);
+                    }
+                    catch {
+                        break;
+                    }
+                    if (nextUrl.protocol !== 'http:' && nextUrl.protocol !== 'https:')
+                        break;
+                    if (redirects >= MAX_REDIRECTS)
+                        return { error: 'too many redirects' };
+                    const hopCheck = await resolveOutboundUrl(nextUrl, resolveHost, controller.signal);
+                    if (hopCheck.blocked)
+                        return { error: hopCheck.blocked };
+                    if (response.status === 303 ||
+                        ((response.status === 301 || response.status === 302) && method === 'POST')) {
+                        method = 'GET';
+                        body = undefined;
+                    }
+                    currentUrl = nextUrl;
+                    validatedAddresses = hopCheck.addresses;
+                    const next = await resolveRedirectBearerHeader(redirectAuth, currentUrl, credentialStore, allowList, ctx, controller.signal);
+                    header = next.header;
+                    credentialKey = next.credentialKey;
+                }
+                const text = await response.text();
+                return { status: response.status, body: truncateResponseBody(text) };
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                return {
+                    error: error.name === 'AbortError' || error instanceof AbortedError
+                        ? 'request timed out'
+                        : `request failed: ${error.message}`
+                };
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+    };
+}

package/dist-lib/lib/tools/mcp/utils.d.ts

@@ -0,0 +1,47 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { ToolExecuteContext } from '../../capabilities/completion.ts';
+import { type FetchInit } from '../http-request/utils.ts';
+export declare const MCP_PROTOCOL_VERSION = "2025-03-26";
+export declare const TIMEOUT_MS = 30000;
+export type McpFetchFn = (url: URL, init: FetchInit) => Promise<{
+    status: number;
+    statusText?: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string> | string;
+}>;
+export declare function isNotification(method: string): boolean;
+export declare function isMetadataMethod(method: unknown): boolean;
+export declare function normalizeMethod(method: string, params: Record<string, unknown> | undefined): {
+    method: string;
+    params: Record<string, unknown> | undefined;
+};
+export declare function flattenMcpResponse(body: string): {
+    error: string;
+} | {
+    body: string;
+};
+export declare function sessionKey(url: string, ctx: ToolExecuteContext | undefined, credentialKey?: string): string;
+export declare function getSession(key: string): string;
+export declare function deleteSession(key: string): void;
+export declare function cacheSession(key: string, sessionId: string): void;
+export declare function post(fetch: McpFetchFn, url: URL, method: string, params: Record<string, unknown> | undefined, authHeader: string | null, sessionId: string | undefined, signal: BareAbortSignal): Promise<{
+    status: number;
+    statusText?: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string> | string;
+}>;
+export declare function readBody(response: {
+    text(): Promise<string> | string;
+    headers: {
+        get(name: string): string | null;
+    };
+}): Promise<string>;
+export declare function needsSession(status: number, cached: string): boolean;
+export declare function establishSession(fetch: McpFetchFn, url: URL, authHeader: string | null, signal: BareAbortSignal): Promise<string | {
+    error: string;
+    stateless?: true;
+}>;