@qvac/harness 0.7.0 → 1.0.0-rc.0

package/dist-lib/lib/serve.js

@@ -1,5 +1,5 @@
-import { AbortController } from 'bare-abort-controller';
 import b4a from 'b4a';
+import { AbortController } from 'bare-abort-controller';
 import fs from 'fs';
 import { settleOnClose } from './rpc-session.js';
 import { pipeline, Readable } from 'streamx';
@@ -8,7 +8,8 @@ import HRPC from '../spec/hrpc/index.js';
 import { isCapability } from './capabilities/invoke.js';
 import { CUSTOM_TASK_TYPES } from './models/model-catalog.js';
 import { unsupportedKvCacheDeletion } from './capabilities/kv-cache.js';
-import { errorMessage } from './guards.js';
+import { validateEngineBoot } from './run-log-protocol.js';
+import { errorMessage, isRecord } from './guards.js';
 import { hlog } from './log.js';
 import { pushQueue } from './queue.js';
 import { TextCoalescer } from './helpers/text-coalescer.js';
@@ -30,6 +31,168 @@ const WIRE_HIGH_WATER_MARK = 64;
 const TEXT_COALESCE_CAP = 8192;
 const TEXT_COALESCE_MS = 60;
 function noop() { }
+function decodeDigestKey(value) {
+    if (typeof value !== 'string' || !/^[0-9a-f]{64}$/i.test(value)) {
+        return undefined;
+    }
+    return b4a.from(value, 'hex');
+}
+function isEngineBoot(value) {
+    if (!isEngineBootEnvelope(value)) {
+        return false;
+    }
+    try {
+        validateEngineBoot(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isEngineBootEnvelope(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const counter = (name) => typeof value[name] === 'number' && Number.isSafeInteger(value[name]) && value[name] >= 0;
+    const metadata = value.metadata;
+    const hasMetadata = metadata === null ||
+        (isRecord(metadata) && metadata.version === 5 && metadata.type === 'metadata');
+    return (value.protocolVersion === 1 &&
+        counter('length') &&
+        counter('nextSeq') &&
+        counter('deltasSinceCheckpoint') &&
+        counter('unredactedLength') &&
+        (value.machineVersion === null || typeof value.machineVersion === 'number') &&
+        (value.xstateVersion === null || typeof value.xstateVersion === 'string') &&
+        hasMetadata &&
+        'eventState' in value &&
+        (value.snapshotSavedAt === undefined || typeof value.snapshotSavedAt === 'number') &&
+        (value.firstSavedAt === undefined || typeof value.firstSavedAt === 'number') &&
+        (value.redactedPendingArgs === null || typeof value.redactedPendingArgs === 'boolean') &&
+        typeof value.restoredRedacted === 'boolean' &&
+        Array.isArray(value.forkBeforeWrite) &&
+        Array.isArray(value.receipts) &&
+        Array.isArray(value.intentArgs));
+}
+const EMPTY_IDENTITY_FIELDS = new Set([
+    'model',
+    'cacheKey',
+    'thinkingDefault',
+    'agent.id',
+    'agent.name',
+    'agent.bio'
+]);
+function startPayloadFrom(value) {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const payload = {};
+    if (value.resume === null || typeof value.resume === 'boolean') {
+        payload.resume = value.resume;
+    }
+    if (value.recoveryEvents === null || typeof value.recoveryEvents === 'boolean') {
+        payload.recoveryEvents = value.recoveryEvents;
+    }
+    if (Object.hasOwn(value, 'explicitEmptyIdentity')) {
+        if (!Array.isArray(value.explicitEmptyIdentity) ||
+            value.explicitEmptyIdentity.length > EMPTY_IDENTITY_FIELDS.size) {
+            throw new TypeError('Invalid explicit-empty identity marker');
+        }
+        const fields = new Set();
+        for (const field of value.explicitEmptyIdentity) {
+            if (typeof field !== 'string' || !EMPTY_IDENTITY_FIELDS.has(field)) {
+                throw new TypeError('Invalid explicit-empty identity marker');
+            }
+            fields.add(field);
+        }
+        if (fields.size) {
+            payload.explicitEmptyIdentity = [...fields];
+        }
+    }
+    if (Array.isArray(value.resolutions)) {
+        payload.resolutions = value.resolutions.map((resolution) => {
+            if (!isRecord(resolution) || typeof resolution.operationId !== 'string') {
+                throw new TypeError('Invalid run recovery resolution');
+            }
+            if (resolution.decision === 'retry') {
+                return { operationId: resolution.operationId, decision: 'retry' };
+            }
+            if (resolution.decision === 'result' && 'result' in resolution) {
+                return {
+                    operationId: resolution.operationId,
+                    decision: 'result',
+                    result: resolution.result
+                };
+            }
+            if (resolution.decision === 'skip') {
+                return { operationId: resolution.operationId, decision: 'skip' };
+            }
+            throw new TypeError('Invalid run recovery resolution');
+        });
+    }
+    if (value.runLog === null) {
+        payload.runLog = null;
+    }
+    else if (value.runLog) {
+        const runLog = isRecord(value.runLog) ? value.runLog : {};
+        payload.runLog = {
+            boot: runLog.boot,
+            digestKey: runLog.digestKey,
+            hostAppendTimeoutMs: typeof runLog.hostAppendTimeoutMs === 'number' ? runLog.hostAppendTimeoutMs : undefined
+        };
+    }
+    return payload;
+}
+function assertEmptyIdentityMarkersMatchFrame(frame, fields) {
+    for (const field of fields) {
+        let value;
+        switch (field) {
+            case 'model':
+                value = frame.model;
+                break;
+            case 'cacheKey':
+                value = frame.cacheKey;
+                break;
+            case 'thinkingDefault':
+                value = frame.thinkingDefault;
+                break;
+            case 'agent.id':
+                if (frame.agent === null || frame.agent === undefined) {
+                    throw new TypeError('Explicit-empty agent identity requires an agent frame');
+                }
+                value = frame.agent?.id;
+                break;
+            case 'agent.name':
+                if (frame.agent === null || frame.agent === undefined) {
+                    throw new TypeError('Explicit-empty agent identity requires an agent frame');
+                }
+                value = frame.agent?.name;
+                break;
+            case 'agent.bio':
+                if (frame.agent === null || frame.agent === undefined) {
+                    throw new TypeError('Explicit-empty agent identity requires an agent frame');
+                }
+                value = frame.agent?.bio;
+                break;
+        }
+        if (value !== null && value !== undefined && value !== '') {
+            throw new TypeError('Conflicting explicit-empty identity marker');
+        }
+    }
+}
+function normalizeAgentKnobs(agent) {
+    const normalized = { ...agent };
+    if (normalized.id === null || normalized.id === undefined) {
+        delete normalized.id;
+    }
+    if (normalized.name === null || normalized.name === undefined) {
+        delete normalized.name;
+    }
+    if (normalized.bio === null || normalized.bio === undefined) {
+        delete normalized.bio;
+    }
+    return normalized;
+}
 function tick() {
     return new Promise((resolve) => setTimeout(resolve, 0));
 }
@@ -270,7 +433,7 @@ function modelEvents(harness) {
             catalogChanged,
             ...loaded.map((entry) => `${entry.model}:${entry.refs}`)
         ].join('\0');
-        if (key === last) {
+        if (key === last && !catalogChanged) {
             return;
         }
         last = key;
@@ -358,10 +521,13 @@ function completion(harness) {
         const pendingRag = new Map();
         const pendingQuestion = new Map();
         const pendingDrive = new Map();
+        const pendingRunLog = new Map();
         const controller = new AbortController();
         let calls = 0;
         let started = false;
+        let clientGone = false;
         const gone = () => {
+            clientGone = true;
             controller.abort('client gone');
             for (const resolve of pending.values()) {
                 resolve(false);
@@ -391,6 +557,10 @@ function completion(harness) {
                 reject(new Error('client gone'));
             }
             pendingDrive.clear();
+            for (const { reject } of pendingRunLog.values()) {
+                reject(new Error('client gone'));
+            }
+            pendingRunLog.clear();
             events.end();
         };
         duplex.on('close', gone);
@@ -501,15 +671,82 @@ function completion(harness) {
                 waiter.resolve(frame.payload ?? {});
                 return;
             }
+            if (frame.type === 'pause') {
+                controller.abort('paused');
+                return;
+            }
+            if (frame.type === 'run-log-result') {
+                if (typeof frame.callId !== 'string') {
+                    return;
+                }
+                const waiter = pendingRunLog.get(frame.callId);
+                pendingRunLog.delete(frame.callId);
+                if (!waiter) {
+                    return;
+                }
+                if (frame.message) {
+                    return waiter.reject(new Error(frame.message));
+                }
+                waiter.resolve();
+                return;
+            }
             if (started || (frame.type !== 'start' && frame.type !== 'invoke')) {
                 return;
             }
             started = true;
+            let startPayload;
+            try {
+                startPayload = startPayloadFrom(frame.payload);
+                assertEmptyIdentityMarkersMatchFrame(frame, startPayload.explicitEmptyIdentity ?? []);
+            }
+            catch (err) {
+                events.push({ type: 'error', message: errorMessage(err) });
+                events.push({ type: 'done' });
+                events.end();
+                return;
+            }
+            const explicitEmptyIdentity = new Set(startPayload.explicitEmptyIdentity ?? []);
+            const runLog = startPayload.runLog;
+            const resuming = startPayload.resume === true ||
+                Boolean(isEngineBoot(runLog?.boot) && runLog.boot.metadata !== null);
+            const requestDigestKey = runLog ? decodeDigestKey(runLog.digestKey) : undefined;
+            const agent = normalizeAgentKnobs(frame.agent ?? {});
+            if ((frame.agent?.id === null || frame.agent?.id === undefined) &&
+                explicitEmptyIdentity.has('agent.id')) {
+                agent.id = '';
+            }
+            if ((frame.agent?.name === null || frame.agent?.name === undefined) &&
+                explicitEmptyIdentity.has('agent.name')) {
+                agent.name = '';
+            }
+            if ((frame.agent?.bio === null || frame.agent?.bio === undefined) &&
+                explicitEmptyIdentity.has('agent.bio')) {
+                agent.bio = '';
+            }
+            const onStep = runLog
+                ? (step) => {
+                    if (clientGone) {
+                        return Promise.reject(new Error('client gone'));
+                    }
+                    return new Promise((resolve, reject) => {
+                        const callId = String(calls++);
+                        pendingRunLog.set(callId, { resolve, reject });
+                        events.push({ type: 'run-log-append', callId, payload: step });
+                    });
+                }
+                : undefined;
             const context = {
+                runId: frame.runId || undefined,
+                resume: resuming,
+                recovery: startPayload.resolutions ?? undefined,
+                boot: isEngineBoot(runLog?.boot) ? runLog.boot : undefined,
+                onStep,
+                requestDigestKey,
+                hostAppendTimeoutMs: runLog?.hostAppendTimeoutMs,
                 model: frame.model ?? '',
-                agent: frame.agent ?? {},
-                cacheKey: frame.cacheKey ?? undefined,
-                thinkingDefault: frame.thinkingDefault ?? undefined,
+                agent,
+                cacheKey: frame.cacheKey ?? (explicitEmptyIdentity.has('cacheKey') ? '' : undefined),
+                thinkingDefault: frame.thinkingDefault ?? (explicitEmptyIdentity.has('thinkingDefault') ? '' : undefined),
                 generationParams: frame.generationParams ?? undefined,
                 responseFormat: frame.responseFormat ?? undefined,
                 captureInferenceCalls: frame.captureInferenceCalls ?? undefined,
@@ -546,7 +783,7 @@ function completion(harness) {
                 approve: (call) => new Promise((resolve) => {
                     const callId = String(calls++);
                     pending.set(callId, resolve);
-                    events.push({
+                    const frame = {
                         type: 'approval-ask',
                         callId,
                         name: call.name,
@@ -555,7 +792,11 @@ function completion(harness) {
                         effect: call.effect,
                         intent: call.intent ?? undefined,
                         display: call.display ?? undefined
-                    });
+                    };
+                    if (call.callId !== undefined || call.round !== undefined) {
+                        frame.payload = { callId: call.callId, round: call.round };
+                    }
+                    events.push(frame);
                 }),
                 attach: async (input) => {
                     const staged = await stageFile('attach', input.bytes);
@@ -613,19 +854,62 @@ function completion(harness) {
                         });
                     })
             };
+            if (resuming) {
+                for (const key of [
+                    'model',
+                    'agent',
+                    'messages',
+                    'cacheKey',
+                    'thinkingDefault',
+                    'generationParams',
+                    'responseFormat'
+                ]) {
+                    const value = frame[key];
+                    const explicitEmpty = (key === 'model' &&
+                        (frame.model === null || frame.model === undefined) &&
+                        explicitEmptyIdentity.has('model')) ||
+                        (key === 'cacheKey' &&
+                            (frame.cacheKey === null || frame.cacheKey === undefined) &&
+                            explicitEmptyIdentity.has('cacheKey')) ||
+                        (key === 'thinkingDefault' &&
+                            (frame.thinkingDefault === null || frame.thinkingDefault === undefined) &&
+                            explicitEmptyIdentity.has('thinkingDefault'));
+                    if ((value === null || value === undefined || value === '') && !explicitEmpty) {
+                        const mutableContext = context;
+                        delete mutableContext[key];
+                    }
+                }
+            }
             void (async () => {
                 let produced = 0;
                 let frames = 0;
+                const textIdentity = {};
                 const text = new TextCoalescer((type, merged) => {
                     frames++;
-                    return events.push({ type, text: merged });
+                    return events.push({ type, text: merged, ...textIdentity });
                 }, { cap: TEXT_COALESCE_CAP, holdMs: TEXT_COALESCE_MS });
                 try {
+                    if (runLog && !requestDigestKey) {
+                        throw new Error('The host did not provide a valid run-log digest key');
+                    }
+                    if (runLog?.boot &&
+                        (!isEngineBoot(runLog.boot) ||
+                            (runLog.boot.metadata !== null && runLog.boot.metadata.runId !== frame.runId))) {
+                        throw new Error('The host did not provide a valid run-log boot');
+                    }
+                    if (resuming && !onStep && !(await harness.capability?.())?.completionRecovery) {
+                        throw new Error('This peer does not support persistent completion recovery');
+                    }
                     for await (const event of runFrame(harness, frame, context)) {
                         produced++;
-                        const wire = toWire(event);
-                        if ((wire.type === 'content' || wire.type === 'thinking') && wire.text) {
-                            await text.add(wire.type, wire.text);
+                        if (!startPayload.recoveryEvents &&
+                            ['run-started', 'run-resumed', 'round-reset', 'recovery-required'].includes(event.type)) {
+                            continue;
+                        }
+                        const wire = !startPayload.recoveryEvents && event.type === 'paused'
+                            ? { type: 'aborted' }
+                            : toWire(event);
+                        if (await accumulateTextFrame(wire, textIdentity, text)) {
                             continue;
                         }
                         await text.flush();
@@ -650,6 +934,18 @@ function completion(harness) {
         hlog('wire handed off');
     };
 }
+async function accumulateTextFrame(wire, identity, text) {
+    if ((wire.type !== 'content' && wire.type !== 'thinking') || !wire.text) {
+        return false;
+    }
+    if (identity.runId !== wire.runId || identity.round !== wire.round) {
+        await text.flush();
+    }
+    identity.runId = wire.runId;
+    identity.round = wire.round;
+    await text.add(wire.type, wire.text);
+    return true;
+}
 function downloadStream(harness, req) {
     const controller = new AbortController();
     const stream = new Readable({

package/dist-lib/lib/spawn.js

@@ -47,7 +47,8 @@ export function spawnHarness(opts) {
     });
     return connectHarness(async () => {
         const { default: Sidecar } = await import('bare-sidecar');
-        const { wrap } = await import('bare-stow/host');
+        const stowHost = await import('bare-stow/host');
+        const IPC = Reflect.get(stowHost, 'IPC');
         const sidecar = new Sidecar(opts.entry, [
             opts.skillsDir ?? '',
             JSON.stringify(opts.sdkStorage),
@@ -63,7 +64,7 @@ export function spawnHarness(opts) {
         ]);
         sidecar.stdout.on('data', (data) => logger?.info('harness', data.toString().trimEnd()));
         sidecar.stderr.on('data', (data) => logger?.warn('harness', data.toString().trimEnd()));
-        const ipc = wrap(sidecar);
+        const ipc = new IPC(sidecar);
         const died = new Promise((resolve) => {
             sidecar.once('exit', (code) => resolve(`harness exited (${code}) before ready`));
         });

package/dist-lib/lib/tool-call-display.d.ts

@@ -1,21 +1 @@
-export interface ToolCallDisplay {
-    readonly label: string;
-    readonly description?: string;
-    readonly iconEmoji?: string;
-}
-export type ToolExecutionOutcome = {
-    readonly kind: 'success';
-} | {
-    readonly kind: 'error';
-    readonly message?: string;
-    readonly error?: unknown;
-} | {
-    readonly kind: 'denied';
-    readonly reason?: string;
-} | {
-    readonly kind: 'blocked';
-    readonly reason?: string;
-} | {
-    readonly kind: 'guidance';
-    readonly message: string;
-};
+export type { ToolCallDisplay, ToolExecutionOutcome } from './machine/index.ts';

package/dist-lib/lib/tools/exec.d.ts

@@ -7,6 +7,7 @@ import type { CredentialStoreFn } from './skills/auth-resolver.ts';
 import { type SkillSettingsFn } from './skills/skill-settings.ts';
 export type { ExecResult, KillProcess, SpawnFn } from './exec/runner.ts';
 export interface ExecToolOptions {
+    readonly policyVersion?: string;
     readonly spawn?: SpawnFn;
     readonly killProcess?: KillProcess;
     readonly loadPyodide?: LoadPyodideFn;
@@ -23,4 +24,4 @@ export interface ScriptRun {
     trusted: boolean;
 }
 export declare function resolveScriptRun(rawArgs: Record<string, unknown>, skillsDir: string | undefined): ScriptRun | ExecError | null;
-export declare function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide, pythonNetwork, credentialStore, skillSettings, realpath, deniedRoots, skillsDir }?: ExecToolOptions): ToolDefinition;
+export declare function createExecTool({ policyVersion, spawn, killProcess, loadPyodide, disablePyodide, pythonNetwork, credentialStore, skillSettings, realpath, deniedRoots, skillsDir }?: ExecToolOptions): ToolDefinition;

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

@@ -1,5 +1,7 @@
 import fs from 'fs';
 import path from 'path';
+import { createHash } from 'crypto';
+import b4a from 'b4a';
 import { AbortedError } from '../helpers/race-abort.js';
 import { checkPdfBuildSource, checkBareLengthArgs, checkPptxBuildSource, checkPythonSource, checkUnstagedRead, createPythonAdapter, isPythonLanguage, parseInputs, parseOutputs, parsePackages, parseWorkdir, pinned, runsThroughPyodide, sandboxInstallError, unwrapPythonSource } from './exec/adapters/python/python-adapter.js';
 import { pythonCreateEffect } from './exec/adapters/python/create-effect.js';
@@ -223,7 +225,39 @@ export function resolveScriptRun(rawArgs, skillsDir) {
     }
     let source;
     try {
-        source = fs.readFileSync(path.join(skillsDir, skill, script), 'utf8');
+        const scriptPath = path.join(skillsDir, skill, script);
+        const regularPath = () => {
+            let current = skillsDir;
+            for (const segment of segments) {
+                current = path.join(current, segment);
+                if (fs.lstatSync(current).isSymbolicLink()) {
+                    return false;
+                }
+            }
+            return true;
+        };
+        if (!regularPath()) {
+            return { error: `script not found in skill ${skill}: ${script}` };
+        }
+        const before = fs.statSync(scriptPath);
+        if (!before.isFile()) {
+            return { error: `script not found in skill ${skill}: ${script}` };
+        }
+        const fd = fs.openSync(scriptPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+        try {
+            const opened = fs.fstatSync(fd);
+            if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino) {
+                return { error: `script not found in skill ${skill}: ${script}` };
+            }
+            source = readScriptSource(fd);
+            const current = fs.statSync(scriptPath);
+            if (!regularPath() || current.dev !== opened.dev || current.ino !== opened.ino) {
+                return { error: `script not found in skill ${skill}: ${script}` };
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
     }
     catch {
         return { error: `script not found in skill ${skill}: ${script}` };
@@ -236,6 +270,18 @@ export function resolveScriptRun(rawArgs, skillsDir) {
     const command = `import sys\nsys.argv = ${argv}\n${source}`;
     return { args: { ...rawArgs, language: 'python', command, scriptArgs }, trusted: true };
 }
+function readScriptSource(fd) {
+    const chunks = [];
+    while (true) {
+        const buffer = b4a.allocUnsafe(8192);
+        const length = fs.readSync(fd, buffer);
+        if (length === 0) {
+            break;
+        }
+        chunks.push(buffer.subarray(0, length));
+    }
+    return b4a.toString(b4a.concat(chunks), 'utf8');
+}
 const SCRIPT_FILE_ARG = /^[\w][\w.-]*\.(pdf|txt|md|csv|docx|xlsx|pptx|png|jpe?g)$/i;
 function stagingGap(rawArgs, scriptArgs) {
     const inputs = parseInputs(rawArgs.inputs);
@@ -301,11 +347,20 @@ async function skillsEnv(skillSettings, ctx) {
     }
     return Object.keys(env).length > 0 ? env : undefined;
 }
-export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide = false, pythonNetwork = !disablePyodide && pythonReachesNetwork(), credentialStore, skillSettings, realpath = defaultRealpath, deniedRoots, skillsDir } = {}) {
+export function createExecTool({ policyVersion, spawn, killProcess, loadPyodide, disablePyodide = false, pythonNetwork = !disablePyodide && pythonReachesNetwork(), credentialStore, skillSettings, realpath = defaultRealpath, deniedRoots, skillsDir } = {}) {
     const adapters = [createPythonAdapter(disablePyodide, loadPyodide, pythonNetwork)];
     const fallback = createShellAdapter({ spawn, killProcess, loadRuntime: bareRuntime });
     return {
         name: 'exec',
+        policyVersion: createHash('sha256')
+            .update(JSON.stringify({
+            version: 1,
+            policyVersion: policyVersion ?? null,
+            disablePyodide,
+            deniedRoots: [...(deniedRoots ?? [])].sort(),
+            skillsDir: skillsDir ?? null
+        }))
+            .digest('hex'),
         toolset: 'exec',
         description: "Execute a shell command on the user's device, or Python via in-process Pyodide. " +
             'One program per call: chaining, pipes, redirection and shell expansion are rejected. ' +

package/dist-lib/lib/tools/generate-image.js

@@ -110,7 +110,7 @@ export function createDiffusionRuntime({ loadSdk, onProgress, onLoaded, onBefore
                         }
                     });
                     try {
-                        const modelId = await Promise.race([loads.track(pending), stall.promise]);
+                        const modelId = await Promise.race([loads.track(pending, sdk), stall.promise]);
                         onLoaded?.(diffusionProgressName(set));
                         return { modelId, prediction: set.prediction };
                     }

package/dist-lib/lib/tools/generate-music.js

@@ -118,7 +118,7 @@ export function createMusicRuntime({ loadSdk, onProgress, onBeforeLoad, loads =
                         modelType: 'audiogen',
                         modelConfig,
                         onProgress: onProgress && ((progress) => onProgress(musicProgressName(stages.dit), progress))
-                    }));
+                    }), sdk);
                     return { modelId };
                 })().catch((err) => {
                     loading = null;

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

@@ -12,9 +12,10 @@ export type FetchFn = (url: URL, init: FetchInit) => Promise<{
 }>;
 export type { CredentialAllowList, CredentialAllowListFn, CredentialRecord, CredentialStoreFn, CredentialStoreValue } from './skills/auth-resolver.ts';
 export interface HttpRequestToolOptions {
+    policyVersion?: string;
     fetch?: FetchFn;
     credentialStore?: CredentialStoreFn;
     credentialAllowList?: CredentialAllowListFn;
     resolveHost?: HostResolver;
 }
-export declare function createHttpRequestTool({ fetch: fetchImpl, credentialStore, credentialAllowList, resolveHost }?: HttpRequestToolOptions): ToolDefinition;
+export declare function createHttpRequestTool({ policyVersion, fetch: fetchImpl, credentialStore, credentialAllowList, resolveHost }?: HttpRequestToolOptions): ToolDefinition;

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

@@ -10,9 +10,10 @@ import { parseAuth, resolveBearerHeader, resolveRedirectBearerHeader } from './s
 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 } = {}) {
+export function createHttpRequestTool({ policyVersion, fetch: fetchImpl, credentialStore, credentialAllowList, resolveHost = lookupHost } = {}) {
     return {
         name: 'http_request',
+        policyVersion,
         toolset: 'http-request',
         description: 'Make an outbound HTTP or HTTPS request and return the response status and body (truncated) as text. 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. For APIs and text responses only: a URL that serves a file — PDF, .docx, .xlsx, an image, any binary — comes back as truncated garbage here. Use web_fetch for those; it downloads and attaches the file.',
         parameters: {

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

@@ -3,8 +3,9 @@ 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 { writeResult } from '../helpers/run-outcome.js';
 import { isRedirectStatus, parseObjectArg } from './http-request/request.js';
-import { cacheSession, deleteSession, establishSession, flattenMcpResponse, getSession, isNotification, needsSession, normalizeMethod, post, readBody, sessionKey, TIMEOUT_MS } from './mcp/protocol.js';
+import { cacheSession, deleteSession, establishSession, flattenMcpResponse, getSession, isMetadataMethod, isNotification, needsSession, normalizeMethod, post, readBody, sessionKey, TIMEOUT_MS } from './mcp/protocol.js';
 import { parseAuth, resolveBearerHeader } from './skills/auth-resolver.js';
 import { recordCredentialHealth } from './skills/credential-health.js';
 import { resolveOutboundUrl } from './url-guard.js';
@@ -75,6 +76,12 @@ export function createMcpCallTool({ fetch: fetchImpl, credentialStore, credentia
                 return null;
             }
         },
+        landedWrite(args, output) {
+            if (isMetadataMethod(args.method)) {
+                return null;
+            }
+            return writeResult(output);
+        },
         async execute(args, ctx) {
             const rawParams = parseMcpParams(args.params);
             if (!rawParams.ok) {

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

@@ -12,6 +12,7 @@ export type BuilderOutcome = {
 export interface OperationBuilder {
     build: (args: Record<string, unknown>) => BuilderOutcome;
 }
+export declare const BUILDER_POLICY_VERSION = 1;
 export declare const BUILDER_NAMES: readonly ['gmail-send', 'gmail-draft', 'gmail-get', '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

@@ -2,6 +2,7 @@ import { randomBytes } from 'crypto';
 import b4a from 'b4a';
 import { z } from 'zod';
 import { buildGmailMessage, GmailEnvelopeSchema } from './gmail-message.js';
+export const BUILDER_POLICY_VERSION = 1;
 export const BUILDER_NAMES = [
     'gmail-send',
     'gmail-draft',