@qvac/harness 0.1.0 → 0.1.1

package/dist-lib/lib/tools/mcp/utils.js

@@ -0,0 +1,172 @@
+import { MAX_RESPONSE_CHARS } from "../http-request/utils.js";
+export const MCP_PROTOCOL_VERSION = '2025-03-26';
+export const TIMEOUT_MS = 30_000;
+const METADATA_METHODS = new Set([
+    'initialize',
+    'ping',
+    'tools/list',
+    'resources/list',
+    'resources/read',
+    'resources/templates/list',
+    'prompts/list',
+    'prompts/get',
+    'completion/complete'
+]);
+const PROTOCOL_METHODS = new Set([...METADATA_METHODS, 'tools/call']);
+export function isNotification(method) {
+    return method.startsWith('notifications/');
+}
+export function isMetadataMethod(method) {
+    return typeof method === 'string' && METADATA_METHODS.has(method);
+}
+export function normalizeMethod(method, params) {
+    if (method === 'tools/call') {
+        const p = params ?? {};
+        return { method, params: p.arguments === undefined ? { ...p, arguments: {} } : p };
+    }
+    if (PROTOCOL_METHODS.has(method) || isNotification(method))
+        return { method, params };
+    return { method: 'tools/call', params: { name: method, arguments: params ?? {} } };
+}
+let nextId = 1;
+function buildEnvelope(method, params) {
+    const envelope = { jsonrpc: '2.0', method };
+    if (params !== undefined)
+        envelope.params = params;
+    if (!isNotification(method))
+        envelope.id = String(nextId++);
+    return JSON.stringify(envelope);
+}
+function headers(authHeader, sessionId) {
+    const h = {
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream'
+    };
+    if (authHeader)
+        h.authorization = authHeader;
+    if (sessionId)
+        h['mcp-session-id'] = sessionId;
+    return h;
+}
+function eventData(event) {
+    return event
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith('data:'))
+        .map((line) => line.slice(line.startsWith('data: ') ? 6 : 5))
+        .join('\n');
+}
+function decodePayload(body, contentType) {
+    let payload = body;
+    if (contentType.includes('text/event-stream')) {
+        const events = body.split(/\r?\n\r?\n/);
+        for (let i = events.length - 1; i >= 0; i--) {
+            const data = eventData(events[i] ?? '');
+            if (data) {
+                payload = data;
+                break;
+            }
+        }
+    }
+    try {
+        return JSON.stringify(JSON.parse(payload), null, 2);
+    }
+    catch {
+        return payload;
+    }
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function contentText(result) {
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return null;
+    const texts = content.flatMap((entry) => {
+        const item = asRecord(entry);
+        return item?.type === 'text' && typeof item.text === 'string' ? [item.text] : [];
+    });
+    return texts.length > 0 ? texts.join('\n\n') : null;
+}
+function rpcErrorText(error) {
+    const message = typeof error.message === 'string' ? error.message.trim() : '';
+    if (error.data === undefined)
+        return message;
+    return `${message} ${JSON.stringify(error.data)}`.trim();
+}
+export function flattenMcpResponse(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return { body: truncate(body) };
+    }
+    const record = asRecord(parsed);
+    if (!record)
+        return { body: truncate(body) };
+    const rpcError = asRecord(record.error);
+    if (rpcError)
+        return { error: truncate(rpcErrorText(rpcError) || body.trim()) };
+    const result = asRecord(record.result);
+    const text = contentText(result)?.trim();
+    if (result?.isError === true)
+        return { error: truncate(text || body.trim()) };
+    return { body: truncate(text || body) };
+}
+function truncate(text) {
+    return text.length > MAX_RESPONSE_CHARS
+        ? `${text.slice(0, MAX_RESPONSE_CHARS)}… [truncated]`
+        : text;
+}
+const SESSION_CACHE = new Map();
+const SESSION_CACHE_MAX = 256;
+export function sessionKey(url, ctx, credentialKey) {
+    return `${url}|${ctx?.agentId ?? ''}|${credentialKey ?? ''}`;
+}
+export function getSession(key) {
+    return SESSION_CACHE.get(key) ?? '';
+}
+export function deleteSession(key) {
+    SESSION_CACHE.delete(key);
+}
+export function cacheSession(key, sessionId) {
+    SESSION_CACHE.set(key, sessionId);
+    if (SESSION_CACHE.size > SESSION_CACHE_MAX) {
+        const oldest = SESSION_CACHE.keys().next().value;
+        if (oldest !== undefined)
+            SESSION_CACHE.delete(oldest);
+    }
+}
+export function post(fetch, url, method, params, authHeader, sessionId, signal) {
+    return fetch(url, {
+        method: 'POST',
+        headers: headers(authHeader, sessionId),
+        body: buildEnvelope(method, params),
+        signal,
+        redirect: 'manual'
+    });
+}
+export async function readBody(response) {
+    return decodePayload(await response.text(), response.headers.get('content-type') ?? '');
+}
+export function needsSession(status, cached) {
+    return status === 400 || (status === 404 && cached !== '');
+}
+export async function establishSession(fetch, url, authHeader, signal) {
+    const init = await post(fetch, url, 'initialize', {
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: 'QV.AC', version: '0.8.x' }
+    }, authHeader, undefined, signal);
+    const sessionId = init.headers.get('mcp-session-id');
+    if (init.status < 200 || init.status >= 300) {
+        return { error: `initialize failed: ${init.status}\n${await readBody(init)}` };
+    }
+    if (!sessionId) {
+        return { error: 'initialize returned no Mcp-Session-Id header', stateless: true };
+    }
+    await post(fetch, url, 'notifications/initialized', undefined, authHeader, sessionId, signal);
+    return sessionId;
+}

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

@@ -0,0 +1,14 @@
+import type { ToolDefinition } from '../capabilities/completion.ts';
+import { type McpFetchFn } from './mcp/utils.ts';
+import { type CredentialAllowListFn, type CredentialStoreFn } from './skills/auth-resolver.ts';
+import { type HostResolver } from './url-guard.ts';
+export type { McpFetchFn };
+export interface McpCallToolOptions {
+    fetch?: McpFetchFn;
+    credentialStore?: CredentialStoreFn;
+    credentialAllowList?: CredentialAllowListFn;
+    readMethods?: ReadonlyMap<string, ReadonlySet<string>>;
+    resolveHost?: HostResolver;
+}
+export declare function mcpTargetUrl(args: Record<string, unknown>): string;
+export declare function createMcpCallTool({ fetch: fetchImpl, credentialStore, credentialAllowList, readMethods, resolveHost }?: McpCallToolOptions): ToolDefinition;

package/dist-lib/lib/tools/mcp-call.js

@@ -0,0 +1,155 @@
+import defaultFetch from '#no-redirect-fetch';
+import { AbortController } from 'bare-abort-controller';
+import { MCP_CALL_TOOL_NAME } from "../capabilities/tool-names.js";
+import { lookupHost } from "../dns-lookup.js";
+import { AbortedError } from "../helpers/race-abort.js";
+import { isRedirectStatus, parseObjectArg } from "./http-request/utils.js";
+import { cacheSession, deleteSession, establishSession, flattenMcpResponse, getSession, isNotification, needsSession, normalizeMethod, post, readBody, sessionKey, TIMEOUT_MS } from "./mcp/utils.js";
+import { parseAuth, resolveBearerHeader } from "./skills/auth-resolver.js";
+import { recordCredentialHealth } from "./skills/credential-health.js";
+import { resolveOutboundUrl } from "./url-guard.js";
+function nestedUrl(params) {
+    return typeof params?.url === 'string' && params.url.length > 0 ? params.url : undefined;
+}
+function parseMcpParams(value) {
+    const parsed = parseObjectArg(value, 'params');
+    if (parsed.ok || typeof value !== 'string')
+        return parsed;
+    return parseObjectArg(value.replace(/[“”]/g, '"'), 'params');
+}
+function toolParams(params, liftedNestedUrl) {
+    if (!params || !liftedNestedUrl)
+        return params;
+    const result = { ...params };
+    delete result.url;
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+export function mcpTargetUrl(args) {
+    if (typeof args.url === 'string' && args.url.length > 0)
+        return args.url;
+    const parsed = parseMcpParams(args.params);
+    return parsed.ok ? (nestedUrl(parsed.value) ?? '') : '';
+}
+export function createMcpCallTool({ fetch: fetchImpl, credentialStore, credentialAllowList, readMethods, resolveHost = lookupHost } = {}) {
+    return {
+        name: MCP_CALL_TOOL_NAME,
+        toolset: 'mcp-call',
+        description: 'Make a JSON-RPC 2.0 call to a Model Context Protocol (MCP) server. Load the matching skill first — it documents the server tool names and their args. Pass a server tool name as `method` and its args as `params`; the JSON-RPC envelope, session handshake, and bearer auth are handled for you (the stored credential for the host is attached automatically, so no `auth` is needed).',
+        parameters: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'Required top-level MCP server URL (https://)' },
+                method: {
+                    type: 'string',
+                    description: 'A server tool name (wrapped into tools/call) or a raw MCP method'
+                },
+                params: {
+                    type: 'object',
+                    description: "The server tool's arguments only; put the MCP server URL in top-level url"
+                },
+                auth: {
+                    type: 'object',
+                    description: 'Optional bearer auth: {"type": "bearer", "tokenCredentialKey": "<key>"}. Pass ONLY the credential key name — never a token value.'
+                }
+            },
+            required: ['url', 'method']
+        },
+        autoApprove: false,
+        effect(args) {
+            if (typeof args.method !== 'string')
+                return 'write';
+            try {
+                const host = new URL(mcpTargetUrl(args)).hostname;
+                return readMethods?.get(host)?.has(args.method) ? 'read' : 'write';
+            }
+            catch {
+                return 'write';
+            }
+        },
+        resource(args) {
+            try {
+                return { kind: 'host', label: new URL(mcpTargetUrl(args)).hostname };
+            }
+            catch {
+                return null;
+            }
+        },
+        async execute(rawArgs, ctx) {
+            const args = rawArgs;
+            const rawParams = parseMcpParams(args.params);
+            if (!rawParams.ok)
+                return { error: rawParams.error };
+            const topLevelUrl = typeof args.url === 'string' && args.url.length > 0 ? args.url : undefined;
+            const urlValue = topLevelUrl ?? nestedUrl(rawParams.value);
+            let url;
+            try {
+                url = new URL(urlValue ?? '');
+            }
+            catch {
+                return { error: `invalid URL: ${String(urlValue)}` };
+            }
+            if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+                return { error: `unsupported protocol: ${url.protocol}` };
+            }
+            if (typeof args.method !== 'string' || args.method.length === 0) {
+                return { error: 'method must be a non-empty string' };
+            }
+            const parsedAuth = parseAuth(args.auth);
+            if (!parsedAuth.ok)
+                return { error: parsedAuth.error };
+            const { method, params } = normalizeMethod(args.method, toolParams(rawParams.value, topLevelUrl === undefined && urlValue !== undefined));
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(undefined), TIMEOUT_MS);
+            try {
+                const urlCheck = await resolveOutboundUrl(url, resolveHost, controller.signal);
+                if (urlCheck.blocked)
+                    return { error: urlCheck.blocked };
+                const bearer = await resolveBearerHeader(parsedAuth.value, url, credentialStore, credentialAllowList?.(ctx), ctx, controller.signal);
+                if ('error' in bearer)
+                    return { error: bearer.error };
+                const authHeader = bearer.header;
+                const fetch = fetchImpl ?? defaultFetch;
+                const guardedFetch = (target, init) => fetch(target, { ...init, validatedAddresses: urlCheck.addresses });
+                const key = sessionKey(url.href, ctx, bearer.credentialKey);
+                const cached = getSession(key);
+                let response = await post(guardedFetch, url, method, params, authHeader, cached || undefined, controller.signal);
+                if (needsSession(response.status, cached)) {
+                    deleteSession(key);
+                    const session = await establishSession(guardedFetch, url, authHeader, controller.signal);
+                    if (typeof session === 'string') {
+                        cacheSession(key, session);
+                        response = await post(guardedFetch, url, method, params, authHeader, session, controller.signal);
+                    }
+                    else if (!session.stateless) {
+                        return { error: session.error };
+                    }
+                }
+                else {
+                    const issued = response.headers.get('mcp-session-id');
+                    if (issued)
+                        cacheSession(key, issued);
+                }
+                if (isRedirectStatus(response.status)) {
+                    return { error: `MCP server responded with an unexpected redirect (${response.status})` };
+                }
+                if (bearer.credentialKey) {
+                    recordCredentialHealth(bearer.credentialKey, response.status, ctx?.agentId);
+                }
+                if (isNotification(method))
+                    return { status: response.status, body: '' };
+                return { status: response.status, ...flattenMcpResponse(await readBody(response)) };
+            }
+            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/model-args.d.ts

@@ -0,0 +1 @@
+export declare function unquoteArg(value: unknown): string;

package/dist-lib/lib/tools/model-args.js

@@ -0,0 +1,4 @@
+import { unwrap } from 'asenion';
+export function unquoteArg(value) {
+    return unwrap(String(value ?? ''));
+}

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

@@ -0,0 +1,17 @@
+export interface OperationRequest {
+    body?: Record<string, unknown>;
+    params?: Record<string, unknown>;
+    encode?: Record<string, string>;
+    query?: Record<string, unknown>;
+}
+export type BuilderOutcome = {
+    request: OperationRequest;
+} | {
+    error: string;
+};
+export interface OperationBuilder {
+    build: (args: Record<string, unknown>) => BuilderOutcome;
+}
+export declare const BUILDER_NAMES: readonly ["gmail-send", "gmail-draft", "calendar-meet-event", "calendar-add-meet", "docs-create", "docs-append-text", "sheets-create", "sheets-write-values", "sheets-append-values", "drive-create-folder", "drive-trash", "notion-create-page", "notion-insert-content"];
+export type BuilderName = (typeof BUILDER_NAMES)[number];
+export declare const BUILDERS: Record<BuilderName, OperationBuilder>;

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

@@ -0,0 +1,179 @@
+import { randomBytes } from 'crypto';
+import b4a from 'b4a';
+import { z } from 'zod';
+import { buildGmailMessage, GmailEnvelopeSchema } from "./gmail-message.js";
+export const BUILDER_NAMES = [
+    'gmail-send',
+    'gmail-draft',
+    'calendar-meet-event',
+    'calendar-add-meet',
+    'docs-create',
+    'docs-append-text',
+    'sheets-create',
+    'sheets-write-values',
+    'sheets-append-values',
+    'drive-create-folder',
+    'drive-trash',
+    'notion-create-page',
+    'notion-insert-content'
+];
+function builder(schema, build) {
+    return {
+        build(args) {
+            const parsed = schema.safeParse(args);
+            if (!parsed.success)
+                return { error: parsed.error.issues[0]?.message ?? 'invalid arguments' };
+            return { request: build(parsed.data) };
+        }
+    };
+}
+const GmailMessageSchema = z
+    .object({ ...GmailEnvelopeSchema.shape, threadId: z.string().optional() })
+    .refine((value) => Boolean(value.text?.length) || Boolean(value.html?.length), {
+    message: 'either text or html is required'
+});
+const gmailSend = builder(GmailMessageSchema, (args) => ({
+    body: { raw: buildGmailMessage(args), threadId: args.threadId },
+    encode: { raw: 'base64url' }
+}));
+const gmailDraft = builder(GmailMessageSchema, (args) => ({
+    body: { message: { raw: buildGmailMessage(args), threadId: args.threadId } },
+    encode: { 'message.raw': 'base64url' }
+}));
+function createRequest() {
+    return {
+        createRequest: {
+            requestId: b4a.toString(randomBytes(16), 'hex'),
+            conferenceSolutionKey: { type: 'hangoutsMeet' }
+        }
+    };
+}
+const MeetEventSchema = z.object({
+    summary: z.string(),
+    start: z.iso.datetime({ offset: true }),
+    end: z.iso.datetime({ offset: true }),
+    timeZone: z.string().optional(),
+    description: z.string().optional(),
+    location: z.string().optional(),
+    attendees: z.array(z.string()).optional(),
+    calendarId: z.string().optional()
+});
+const calendarMeetEvent = builder(MeetEventSchema, (args) => ({
+    body: {
+        summary: args.summary,
+        description: args.description,
+        location: args.location,
+        start: { dateTime: args.start, timeZone: args.timeZone },
+        end: { dateTime: args.end, timeZone: args.timeZone },
+        attendees: args.attendees?.map((email) => ({ email })),
+        conferenceData: createRequest()
+    },
+    query: { conferenceDataVersion: 1 }
+}));
+const AddMeetSchema = z.object({
+    eventId: z.string(),
+    calendarId: z.string().optional()
+});
+const calendarAddMeet = builder(AddMeetSchema, () => ({
+    body: { conferenceData: createRequest() },
+    query: { conferenceDataVersion: 1 }
+}));
+const docsCreate = builder(z.object({ title: z.string().min(1) }), (args) => ({
+    body: { title: args.title }
+}));
+const DocsAppendSchema = z.object({
+    documentId: z.string().min(1),
+    text: z.string().min(1),
+    pageBreak: z.boolean().optional()
+});
+const docsAppendText = builder(DocsAppendSchema, (args) => {
+    const requests = [
+        { insertText: { endOfSegmentLocation: {}, text: args.text } }
+    ];
+    if (args.pageBreak)
+        requests.push({ insertPageBreak: { endOfSegmentLocation: {} } });
+    return { body: { requests } };
+});
+const sheetsCreate = builder(z.object({ name: z.string().min(1) }), (args) => ({
+    body: { name: args.name, mimeType: 'application/vnd.google-apps.spreadsheet' }
+}));
+const Cell = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const SheetsValuesSchema = z.object({
+    spreadsheetId: z.string().min(1),
+    range: z.string().min(1),
+    values: z.array(z.array(Cell)).min(1),
+    valueInputOption: z.enum(['RAW', 'USER_ENTERED']).optional()
+});
+const sheetsWriteValues = builder(SheetsValuesSchema, (args) => ({
+    body: { range: args.range, values: args.values },
+    query: { valueInputOption: args.valueInputOption ?? 'USER_ENTERED' }
+}));
+const sheetsAppendValues = builder(SheetsValuesSchema, (args) => ({
+    body: { values: args.values },
+    query: { valueInputOption: args.valueInputOption ?? 'USER_ENTERED' }
+}));
+const DriveFolderSchema = z.object({
+    name: z.string().min(1),
+    parentId: z.string().optional()
+});
+const driveCreateFolder = builder(DriveFolderSchema, (args) => ({
+    body: {
+        name: args.name,
+        mimeType: 'application/vnd.google-apps.folder',
+        parents: args.parentId ? [args.parentId] : undefined
+    }
+}));
+const driveTrash = builder(z.object({ fileId: z.string().min(1) }), () => ({
+    body: { trashed: true }
+}));
+const NotionCreatePageSchema = z
+    .object({
+    title: z.string().min(1),
+    content: z.string().optional(),
+    parentPageId: z.string().optional(),
+    parentDatabaseId: z.string().optional()
+})
+    .refine((value) => !(value.parentPageId && value.parentDatabaseId), {
+    message: 'pass parentPageId or parentDatabaseId, not both'
+});
+function notionParent(args) {
+    if (args.parentPageId)
+        return { page_id: args.parentPageId };
+    if (args.parentDatabaseId)
+        return { database_id: args.parentDatabaseId };
+    return undefined;
+}
+const notionCreatePage = builder(NotionCreatePageSchema, (args) => ({
+    params: {
+        parent: notionParent(args),
+        pages: [{ properties: { title: args.title }, content: args.content }]
+    }
+}));
+const NotionInsertSchema = z.object({
+    pageId: z.string().min(1),
+    content: z.string().min(1),
+    position: z.enum(['start', 'end']).optional()
+});
+const notionInsertContent = builder(NotionInsertSchema, (args) => ({
+    params: {
+        page_id: args.pageId,
+        command: 'insert_content',
+        content: args.content,
+        position: args.position === 'start' ? { type: 'start' } : undefined
+    }
+}));
+export const BUILDERS = {
+    'gmail-send': gmailSend,
+    'gmail-draft': gmailDraft,
+    'calendar-meet-event': calendarMeetEvent,
+    'calendar-add-meet': calendarAddMeet,
+    'docs-create': docsCreate,
+    'docs-append-text': docsAppendText,
+    'sheets-create': sheetsCreate,
+    'sheets-write-values': sheetsWriteValues,
+    'sheets-append-values': sheetsAppendValues,
+    'drive-create-folder': driveCreateFolder,
+    'drive-trash': driveTrash,
+    'notion-create-page': notionCreatePage,
+    'notion-insert-content': notionInsertContent
+};

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

@@ -0,0 +1,7 @@
+import type { ToolDefinition } from '../../capabilities/completion.ts';
+import type { SkillCatalogEntry } from '../skills/catalog.ts';
+export interface CompileOperationToolsOptions {
+    httpRequestTool: ToolDefinition;
+    mcpCallTool?: ToolDefinition;
+}
+export declare function compileOperationTools(catalog: readonly SkillCatalogEntry[], { httpRequestTool, mcpCallTool }: CompileOperationToolsOptions): ToolDefinition[];

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

@@ -0,0 +1,92 @@
+import { BUILDERS } from "./builders.js";
+export function compileOperationTools(catalog, { httpRequestTool, mcpCallTool }) {
+    return catalog.flatMap((entry) => (entry.operations ?? []).flatMap((operation) => {
+        const transport = operation.request.transport === 'mcp' ? mcpCallTool : httpRequestTool;
+        return transport ? [operationTool(entry.name, operation, transport)] : [];
+    }));
+}
+function operationTool(owningSkill, operation, transportTool) {
+    const builder = BUILDERS[operation.request.builder];
+    const mcp = operation.request.transport === 'mcp';
+    return {
+        name: operation.tool,
+        owningSkill,
+        description: operation.description,
+        parameters: operation.parameters,
+        autoApprove: false,
+        skillGated: true,
+        externalWrite: true,
+        toolset: mcp ? 'mcp-call' : 'http-request',
+        compiled: true,
+        effect() {
+            return 'write';
+        },
+        resource() {
+            return hostOf(operation.request.url);
+        },
+        async execute(args, ctx) {
+            const skillContext = { ...ctx, skills: [owningSkill] };
+            const built = builder.build(args);
+            if ('error' in built)
+                return { error: `${operation.tool}: ${built.error}` };
+            const request = operation.request;
+            if (request.transport === 'mcp') {
+                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)
+                return { error: `${operation.tool}: ${url.error}` };
+            const result = await transportTool.execute({
+                url: url.value,
+                method: request.method,
+                query: { ...request.query, ...built.request.query },
+                body: built.request.body,
+                encode: built.request.encode
+            }, skillContext);
+            return operation.response ? pickResponse(result, operation.response.pick) : result;
+        }
+    };
+}
+function pickResponse(result, keys) {
+    if (!result || typeof result !== 'object')
+        return result;
+    const { body, status } = result;
+    if (typeof body !== 'string' || (typeof status === 'number' && status >= 400))
+        return result;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return result;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return result;
+    const record = parsed;
+    const picked = {};
+    for (const key of keys)
+        if (key in record)
+            picked[key] = record[key];
+    return { ...result, body: JSON.stringify(picked) };
+}
+const PLACEHOLDER = /\{(\w+)\}/g;
+function fillTemplate(template, args, defaults) {
+    const missing = [];
+    const value = template.replace(PLACEHOLDER, (_match, name) => {
+        const filled = args[name] ?? defaults?.[name];
+        if (filled === undefined)
+            missing.push(name);
+        return encodeURIComponent(String(filled));
+    });
+    if (missing.length)
+        return { error: `missing required argument ${missing.join(', ')}` };
+    return { value };
+}
+function hostOf(url) {
+    try {
+        return { kind: 'host', label: new URL(url).hostname };
+    }
+    catch {
+        return null;
+    }
+}

package/dist-lib/lib/tools/operations/gmail-message.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export declare const GmailEnvelopeSchema: z.ZodObject<{
+    to: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    cc: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    bcc: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    subject: z.ZodString;
+    text: z.ZodOptional<z.ZodString>;
+    html: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+    replyTo: z.ZodOptional<z.ZodString>;
+    inReplyTo: z.ZodOptional<z.ZodString>;
+    references: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GmailEnvelope = z.infer<typeof GmailEnvelopeSchema>;
+export declare function buildGmailMessage(envelope: GmailEnvelope): string;