@qvac/harness 0.3.0 → 0.3.1

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

@@ -0,0 +1,10 @@
+export declare const PYTHON_BIN_ERROR: string;
+export declare const PACKAGES_NEED_PYTHON_ERROR: string;
+export declare const FILES_NEED_PYTHON_ERROR: string;
+export declare function videoToolError(command: string, packages: readonly string[] | undefined, python: boolean, network?: boolean): string | null;
+export declare const SHELL_DOWNLOAD_NOTE: string;
+export declare function shellDownloadNote(command: string): string | null;
+export declare function pipError(command: string, sandbox?: boolean): string | null;
+export declare function startsLikePython(command: string): boolean;
+export declare function isPythonSourceShaped(command: string): boolean;
+export declare function pythonRedirectError(command: string, sandbox?: boolean): string | null;

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

@@ -0,0 +1,123 @@
+import { pipInstallTargets, pipMessage, unwrapPythonSource, withoutProgramDir } from './adapters/python/python-adapter.js';
+import { bareBin, firstCommandToken, sanitizeCommand } from './scope.js';
+import { shellArgv } from './shell-argv.js';
+import { downloaderShellError, isTranscoder, TRANSCODE_ERROR, VIDEO_TOOLS_ERROR, videoTool } from './video-tools.js';
+const INTERPRETER = /^(python[\d.]*|py)$/;
+const PIP = /^pip[\d.]*$/;
+export const PYTHON_BIN_ERROR = 'python is not a shell command here. Call exec with language "python" and command set to the ' +
+    'Python source itself: drop "python -c" and the quotes around the code. PyPI names go in packages.';
+export const PACKAGES_NEED_PYTHON_ERROR = 'packages only work with language "python". Call exec with language "python", the same packages ' +
+    'and the Python source in command.';
+export const FILES_NEED_PYTHON_ERROR = 'inputs and outputs only work with language "python". Call exec with language "python" and the ' +
+    'Python source in command.';
+function commandBin(command) {
+    return bareBin(firstCommandToken(command).replace(/^.*[/\\]/, '')) ?? '';
+}
+function dashModule(command) {
+    return /^\s*(?:python[\d.]*|py)\s+-m\s+([\w.-]+)/.exec(withoutProgramDir(command))?.[1] ?? null;
+}
+function importedModules(source) {
+    const modules = [];
+    for (const line of source.split('\n')) {
+        const from = /^\s*from\s+([\w.]+)\s+import\b/.exec(line)?.[1];
+        if (from) {
+            modules.push(from);
+            continue;
+        }
+        const imported = /^\s*import\s+([\w.]+(?:\s*,\s*[\w.]+)*)/.exec(line)?.[1];
+        if (imported)
+            modules.push(...imported.split(',').map((m) => m.trim()));
+    }
+    return modules.map((m) => m.split('.')[0]);
+}
+export function videoToolError(command, packages, python, network = false) {
+    const names = [
+        dashModule(command) ?? '',
+        ...(pipInstallTargets(command) ?? []),
+        ...(packages ?? []),
+        ...(python ? importedModules(unwrapPythonSource(command) ?? command) : [commandBin(command)])
+    ];
+    const tools = names.map(videoTool).filter((tool) => tool !== null);
+    if (tools.length === 0)
+        return null;
+    if (!network)
+        return VIDEO_TOOLS_ERROR;
+    if (tools.some(isTranscoder))
+        return TRANSCODE_ERROR;
+    if (python)
+        return null;
+    const program = videoTool(commandBin(command)) ?? videoTool(dashModule(command) ?? '');
+    return program ? downloaderShellError(program) : null;
+}
+export const SHELL_DOWNLOAD_NOTE = "The file was saved on this device's disk, not in the chat, so the user cannot see it. To " +
+    'give the user a downloaded file, fetch it in exec with language "python" and declare it in outputs.';
+const CURL_VALUED = new Set('AbcCdDeEFHKmoPQrTuUwxXyYz'.split(''));
+const WGET_VALUED = new Set('aABDeIilOoPQRtTUwX'.split(''));
+function writesFile(words, curl) {
+    const valued = curl ? CURL_VALUED : WGET_VALUED;
+    const output = curl ? 'o' : 'O';
+    const long = curl ? '--output' : '--output-document';
+    let saves = !curl;
+    for (let i = 1; i < words.length; i++) {
+        const word = words[i];
+        if (curl && /^--remote-name(-all)?$/.test(word))
+            saves = true;
+        if (word === long || word.startsWith(`${long}=`)) {
+            const value = word === long ? words[++i] : word.slice(long.length + 1);
+            saves = value !== '-';
+            continue;
+        }
+        if (!/^-[A-Za-z]/.test(word))
+            continue;
+        for (let j = 1; j < word.length; j++) {
+            const flag = word[j];
+            if (curl && flag === 'O')
+                saves = true;
+            if (!valued.has(flag))
+                continue;
+            const value = j + 1 < word.length ? word.slice(j + 1) : words[++i];
+            if (flag === output)
+                saves = value !== '-';
+            break;
+        }
+    }
+    return saves;
+}
+export function shellDownloadNote(command) {
+    const bin = commandBin(command);
+    if (bin !== 'curl' && bin !== 'wget')
+        return null;
+    return writesFile(shellArgv(command), bin === 'curl') ? SHELL_DOWNLOAD_NOTE : null;
+}
+export function pipError(command, sandbox = false) {
+    if (!PIP.test(commandBin(command)) && dashModule(command) !== 'pip')
+        return null;
+    return pipMessage(pipInstallTargets(command), sandbox);
+}
+function firstCodeLine(command) {
+    return (command
+        .split('\n')
+        .find((line) => line.trim() && !line.trim().startsWith('#'))
+        ?.trim() ?? '');
+}
+const PYTHON_START = /^(from\s+[\w.]+\s+import\b|import\s+[\w.]+\s*(,|;|$|\sas\s)|def\s+\w+\s*\(|class\s+\w+|@[\w.]+|(for|while|if|with|try|async)\b[^\n]*:$|"""|\'\'\'|[A-Za-z_][\w.]*(\[[^\]]*\])?\s+=\s+)/;
+export function startsLikePython(command) {
+    return PYTHON_START.test(firstCodeLine(command));
+}
+export function isPythonSourceShaped(command) {
+    const first = firstCodeLine(command);
+    if (/^from\s+[\w.]+\s+import\b/.test(first))
+        return true;
+    if (/^[A-Za-z_][\w.]*\s*\(/.test(first) && !/^[A-Za-z_]\w*\s*\(\s*\)\s*\{/.test(first)) {
+        return true;
+    }
+    if (!PYTHON_START.test(first))
+        return false;
+    return command.trim().includes('\n') || sanitizeCommand(command) !== null;
+}
+export function pythonRedirectError(command, sandbox = false) {
+    const pip = pipError(command, sandbox);
+    if (pip)
+        return pip;
+    return INTERPRETER.test(commandBin(command)) ? PYTHON_BIN_ERROR : null;
+}

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

@@ -0,0 +1,5 @@
+export declare const VIDEO_TOOLS_ERROR: string;
+export declare const TRANSCODE_ERROR: string;
+export declare function downloaderShellError(tool: string): string;
+export declare function videoTool(name: string): string | null;
+export declare function isTranscoder(tool: string): boolean;

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

@@ -0,0 +1,40 @@
+const TRANSCODERS = new Set([
+    'ffmpeg',
+    'ffprobe',
+    'ffmpeg-python',
+    'imageio-ffmpeg',
+    'moviepy',
+    'avconv',
+    'ytdl'
+]);
+const DOWNLOADERS = new Set([
+    'yt-dlp',
+    'youtube-dl',
+    'you-get',
+    'streamlink',
+    'pytube',
+    'pytubefix'
+]);
+export const VIDEO_TOOLS_ERROR = 'downloading or transcoding video is not possible on this device: yt-dlp, youtube-dl, ffmpeg ' +
+    'and similar tools cannot run here, on any path. Do not retry; tell the user it cannot be done.';
+export const TRANSCODE_ERROR = 'ffmpeg is not available on this device: ffmpeg, ffprobe and the packages that run them ' +
+    '(moviepy, ffmpeg-python) cannot run here, on any path, so nothing can merge or convert ' +
+    'video. Fetch a single file that needs neither, or tell the user it cannot be done.';
+export function downloaderShellError(tool) {
+    return (`${tool} is not a program here: it is a Python package. Call exec with language "python", ` +
+        `packages: ["${tool}"] and Python source that imports it, and declare the file it saves ` +
+        'in outputs so it reaches the user.');
+}
+export function videoTool(name) {
+    const bare = name
+        .trim()
+        .replace(/^['"]|['"]$/g, '')
+        .split(/[=<>!~[\s]/)[0]
+        .toLowerCase()
+        .replace(/\.exe$/, '')
+        .replace(/[-_.]+/g, '-');
+    return TRANSCODERS.has(bare) || DOWNLOADERS.has(bare) ? bare : null;
+}
+export function isTranscoder(tool) {
+    return TRANSCODERS.has(tool);
+}

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

@@ -10,6 +10,7 @@ export interface ExecToolOptions {
     readonly killProcess?: KillProcess;
     readonly loadPyodide?: LoadPyodideFn;
     readonly disablePyodide?: boolean;
+    readonly pythonNetwork?: boolean;
     readonly credentialStore?: CredentialStoreFn;
     readonly skillSettings?: SkillSettingsFn;
     readonly realpath?: Realpath;
@@ -26,4 +27,4 @@ export declare function resolveScriptRun(rawArgs: Record<string, unknown>, skill
 } | {
     error: string;
 } | null;
-export declare function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide, credentialStore, skillSettings, realpath, deniedRoots, skillsDir }?: ExecToolOptions): ToolDefinition;
+export declare function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide, pythonNetwork, credentialStore, skillSettings, realpath, deniedRoots, skillsDir }?: ExecToolOptions): ToolDefinition;

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

@@ -2,12 +2,14 @@ import fs from 'fs';
 import path from 'path';
 import { AbortedError } from '../helpers/race-abort.js';
 import { spawnEnv } from '../helpers/spawn-path.js';
-import { checkPdfBuildSource, checkBareLengthArgs, checkPptxBuildSource, checkPythonSource, checkUnstagedRead, createPythonAdapter, isPythonLanguage, looksLikePythonSource, parseInputs, parseOutputs, parsePackages, parseWorkdir, runsThroughPyodide, unwrapPythonSource } from './exec/adapters/python/python-adapter.js';
+import { checkPdfBuildSource, checkBareLengthArgs, checkPptxBuildSource, checkPythonSource, checkUnstagedRead, createPythonAdapter, isPythonLanguage, parseInputs, parseOutputs, parsePackages, parseWorkdir, pinned, runsThroughPyodide, unwrapPythonSource } from './exec/adapters/python/python-adapter.js';
 import { pythonCreateEffect } from './exec/adapters/python/create-effect.js';
+import { pythonReachesNetwork } from './exec/adapters/python/net-shim.js';
 import { createShellAdapter } from './exec/adapters/shell/shell-adapter.js';
 import { routeObsidianCommand } from './exec/obsidian/route.js';
 import { MAX_OUTPUT_CHARS_LIMIT } from './exec/runner.js';
 import { bareBin, firstCommandToken, sanitizeCommand } from './exec/scope.js';
+import { FILES_NEED_PYTHON_ERROR, isPythonSourceShaped, PACKAGES_NEED_PYTHON_ERROR, pythonRedirectError, startsLikePython, videoToolError } from './exec/shell-guidance.js';
 import { shellArgv } from './exec/shell-argv.js';
 import { canonicalDenyRoots, defaultRealpath, hostPath, resolveKey } from './fs/scope.js';
 import { unquoteArg } from './model-args.js';
@@ -64,7 +66,7 @@ function isPresent(value) {
 }
 function checkFileArgs(args, python) {
     if (!python && (isPresent(args.inputs) || isPresent(args.outputs))) {
-        return 'inputs and outputs require language "python" with Pyodide enabled';
+        return FILES_NEED_PYTHON_ERROR;
     }
     const inputs = parseInputs(args.inputs);
     if (inputs && 'error' in inputs)
@@ -100,13 +102,25 @@ function fileSuffix(args) {
     const to = Array.isArray(outputs) && outputs.length > 0 ? ` → ${truncateLabel(outputs.join(', '))}` : '';
     return `${from}${to}`;
 }
-const PYTHON_BINS = new Set(['python', 'python3', 'py', 'pip', 'pip3']);
-function commandRequiredError(args) {
+function stringList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((v) => typeof v === 'string');
+}
+function commandRequiredError(args, network) {
     const staged = Array.isArray(args.inputs) || Array.isArray(args.outputs);
-    return staged
-        ? 'command is required: keep these same inputs/outputs and add either command (the bare ' +
-            'python source) or script + scriptArgs exactly as the loaded skill reference shows'
-        : 'command is required';
+    if (staged) {
+        return ('command is required: keep these same inputs/outputs and add either command (the bare ' +
+            'python source) or script + scriptArgs exactly as the loaded skill reference shows');
+    }
+    const packages = stringList(args.packages);
+    const impossible = videoToolError('', packages, true, network);
+    if (impossible)
+        return impossible;
+    if (packages?.length) {
+        return `command is required: call exec again with language "python", packages: ${JSON.stringify(packages.map(pinned))} and the Python source that uses them in command. Installing and running are the same one call.`;
+    }
+    return 'command is required';
 }
 function parseScriptArgs(value) {
     if (Array.isArray(value))
@@ -207,18 +221,27 @@ function scriptLabel(args) {
 }
 const WORKDIR_NO_ROOTS_ERROR = 'workdir is not available: no directories are granted to this device, so a working directory ' +
     'cannot be validated. Omit workdir and use absolute paths in the command.';
-function checkExecutionScope(args, toolOps, disablePyodide) {
+function withInferredLanguage(args, disablePyodide) {
+    if (disablePyodide || isPythonLanguage(args.language))
+        return args;
+    const command = String(args.command ?? '').trim();
+    const declared = (stringList(args.packages) ?? []).length > 0 && startsLikePython(command);
+    const wrapped = unwrapPythonSource(command) !== null;
+    return isPythonSourceShaped(command) || declared || wrapped
+        ? { ...args, language: 'python' }
+        : args;
+}
+function checkExecutionScope(args, toolOps, disablePyodide, sandbox, network) {
     const command = String(args.command ?? '').trim();
+    const video = videoToolError(command, stringList(args.packages), runsThroughPyodide(args.language, disablePyodide), network);
+    if (video)
+        return video;
     if (runsThroughPyodide(args.language, disablePyodide))
         return null;
-    if (!disablePyodide && PYTHON_BINS.has(bareBin(firstCommandToken(command)) ?? '')) {
-        return 'run Python by passing language="python" with the bare Python source in command; the exec shell path does not run python or pip';
-    }
-    const callsFirst = /^[A-Za-z_][\w.]*\s*\(/.test(command);
-    const sourceShaped = (/^from\s+\w+\s+import\b/.test(command) || command.includes('\n')) &&
-        looksLikePythonSource(command);
-    if (!disablePyodide && (callsFirst || sourceShaped)) {
-        return 'this command is Python source: pass language "python" with the bare source in command (dependencies in packages, produced files in outputs)';
+    if (!disablePyodide) {
+        const redirect = pythonRedirectError(command, sandbox);
+        if (redirect)
+            return redirect;
     }
     return checkShellScope(command, toolOps);
 }
@@ -232,8 +255,8 @@ async function skillsEnv(skillSettings, ctx) {
     }
     return Object.keys(env).length > 0 ? env : undefined;
 }
-export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide = false, credentialStore, skillSettings, realpath = defaultRealpath, deniedRoots, skillsDir } = {}) {
-    const adapters = [createPythonAdapter(disablePyodide, loadPyodide)];
+export function createExecTool({ 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',
@@ -347,7 +370,8 @@ export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide
             }
         },
         autoApprove: false,
-        effect(args, ctx) {
+        effect(rawArgs, ctx) {
+            const args = withInferredLanguage(rawArgs, disablePyodide);
             if (typeof args.script === 'string' && args.script.trim() && !args.script.includes('\n')) {
                 return 'read';
             }
@@ -359,11 +383,11 @@ export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide
             const scriptRun = resolveScriptRun(args, skillsDir);
             if (scriptRun && 'error' in scriptRun)
                 return scriptRun.error;
-            const rawArgs = scriptRun ? scriptRun.args : args;
+            const rawArgs = withInferredLanguage(scriptRun ? scriptRun.args : args, disablePyodide);
             const command = String(rawArgs.command ?? '').trim();
             if (!command)
-                return commandRequiredError(rawArgs);
-            const scopeError = checkExecutionScope(rawArgs, ctx?.toolOps, disablePyodide);
+                return commandRequiredError(rawArgs, pythonNetwork && ctx?.sandboxMode !== true);
+            const scopeError = checkExecutionScope(rawArgs, ctx?.toolOps, disablePyodide, ctx?.sandboxMode === true, pythonNetwork && ctx?.sandboxMode !== true);
             if (scopeError)
                 return scopeError;
             const python = runsThroughPyodide(rawArgs.language, disablePyodide);
@@ -400,12 +424,12 @@ export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide
             const parsed = parsePackages(rawArgs.packages);
             if (parsed && 'error' in parsed)
                 return parsed.error;
-            if (parsed && !python) {
-                return 'packages require language "python" with Pyodide enabled';
-            }
+            if (parsed && !python)
+                return PACKAGES_NEED_PYTHON_ERROR;
             return checkFileArgs(rawArgs, python);
         },
-        resource(args) {
+        resource(rawArgs) {
+            const args = withInferredLanguage(rawArgs, disablePyodide);
             const script = typeof args.script === 'string' ? args.script : '';
             if (script.trim() && !script.includes('\n')) {
                 return { kind: 'command', label: scriptLabel(args) };
@@ -426,11 +450,12 @@ export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide
             const scriptRun = resolveScriptRun(args, skillsDir);
             if (scriptRun && 'error' in scriptRun)
                 return { error: scriptRun.error };
-            const rawArgs = scriptRun ? scriptRun.args : args;
+            const rawArgs = withInferredLanguage(scriptRun ? scriptRun.args : args, disablePyodide);
             const command = String(rawArgs.command ?? '').trim();
-            if (!command)
-                return { error: commandRequiredError(rawArgs) };
-            const scopeError = checkExecutionScope(rawArgs, ctx?.toolOps, disablePyodide);
+            if (!command) {
+                return { error: commandRequiredError(rawArgs, pythonNetwork && ctx?.sandboxMode !== true) };
+            }
+            const scopeError = checkExecutionScope(rawArgs, ctx?.toolOps, disablePyodide, ctx?.sandboxMode === true, pythonNetwork && ctx?.sandboxMode !== true);
             if (scopeError)
                 return { error: scopeError };
             const workdir = rawArgs.workdir === undefined || rawArgs.workdir === null
@@ -488,7 +513,9 @@ export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide
                     attach: ctx?.attach,
                     fetchAttachment: ctx?.fetchAttachment,
                     turnImages: ctx?.turnImages,
-                    runBudget: ctx?.runBudget
+                    runBudget: ctx?.runBudget,
+                    sandboxMode: ctx?.sandboxMode,
+                    toolNames: ctx?.toolNames
                 });
                 return await execution.run({
                     cwd,

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

@@ -1 +1,2 @@
 export declare function truncateResponseBody(body: string): string;
+export declare const ELISION = "\u2026 [truncated]";

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

@@ -20,7 +20,7 @@ function shrinkable(value) {
         return true;
     return typeof value === 'object' && value !== null;
 }
-const ELISION = '… [truncated]';
+export const ELISION = '… [truncated]';
 function fitString(value, budget) {
     const room = budget - ELISION.length - 2;
     if (room <= 0)

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

@@ -159,7 +159,10 @@ export function createHttpRequestTool({ fetch: fetchImpl, credentialStore, crede
                     credentialKey = next.credentialKey;
                 }
                 const text = await response.text();
-                return { status: response.status, body: truncateResponseBody(text) };
+                return {
+                    status: response.status,
+                    body: ctx?.uncappedResponse ? text : truncateResponseBody(text)
+                };
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));

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

@@ -12,6 +12,6 @@ export type BuilderOutcome = {
 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 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

@@ -5,6 +5,7 @@ import { buildGmailMessage, GmailEnvelopeSchema } from './gmail-message.js';
 export const BUILDER_NAMES = [
     'gmail-send',
     'gmail-draft',
+    'gmail-get',
     'calendar-meet-event',
     'calendar-add-meet',
     'docs-create',
@@ -40,6 +41,13 @@ const gmailDraft = builder(GmailMessageSchema, (args) => ({
     body: { message: { raw: buildGmailMessage(args), threadId: args.threadId } },
     encode: { 'message.raw': 'base64url' }
 }));
+const GmailGetSchema = z.object({
+    id: z.string().min(1),
+    format: z.enum(['metadata', 'full']).optional()
+});
+const gmailGet = builder(GmailGetSchema, (args) => ({
+    query: { format: args.format ?? 'metadata' }
+}));
 function createRequest() {
     return {
         createRequest: {
@@ -165,6 +173,7 @@ const notionInsertContent = builder(NotionInsertSchema, (args) => ({
 export const BUILDERS = {
     'gmail-send': gmailSend,
     'gmail-draft': gmailDraft,
+    'gmail-get': gmailGet,
     'calendar-meet-event': calendarMeetEvent,
     'calendar-add-meet': calendarAddMeet,
     'docs-create': docsCreate,

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

@@ -1,4 +1,8 @@
+import { z } from 'zod';
+import { READ_METHODS } from '../http-methods.js';
+import { truncateResponseBody } from '../http-request/truncate-response.js';
 import { BUILDERS } from './builders.js';
+import { DECODERS } from './decoders.js';
 export function compileOperationTools(catalog, { httpRequestTool, mcpCallTool }) {
     return catalog.flatMap((entry) => (entry.operations ?? []).flatMap((operation) => {
         const transport = operation.request.transport === 'mcp' ? mcpCallTool : httpRequestTool;
@@ -8,18 +12,19 @@ export function compileOperationTools(catalog, { httpRequestTool, mcpCallTool })
 function operationTool(owningSkill, operation, transportTool) {
     const builder = BUILDERS[operation.request.builder];
     const mcp = operation.request.transport === 'mcp';
+    const read = !mcp && READ_METHODS.has(operation.request.method);
     return {
         name: operation.tool,
         owningSkill,
         description: operation.description,
         parameters: operation.parameters,
-        autoApprove: false,
+        autoApprove: read,
         skillGated: true,
-        externalWrite: true,
+        externalWrite: !read,
         toolset: mcp ? 'mcp-call' : 'http-request',
         compiled: true,
         effect() {
-            return 'write';
+            return read ? 'read' : 'write';
         },
         resource() {
             return hostOf(operation.request.url);
@@ -29,6 +34,9 @@ function operationTool(owningSkill, operation, transportTool) {
             const built = builder.build(args);
             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` };
+            }
             const request = operation.request;
             if (request.transport === 'mcp') {
                 return transportTool.execute({ url: request.url, method: request.method, params: built.request.params }, skillContext);
@@ -36,38 +44,53 @@ function operationTool(owningSkill, operation, transportTool) {
             const url = fillTemplate(request.url, args, request.urlDefaults);
             if ('error' in url)
                 return { error: `${operation.tool}: ${url.error}` };
+            const { response } = operation;
             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;
+            }, response ? { ...skillContext, uncappedResponse: true } : skillContext);
+            return response ? capBody(shapeResponse(result, response)) : result;
         }
     };
 }
-function pickResponse(result, keys) {
-    if (!result || typeof result !== 'object')
+const JsonResult = z.looseObject({ status: z.number().optional(), body: z.string() });
+function capBody(result) {
+    const parsed = JsonResult.safeParse(result);
+    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)
         return result;
-    const { body, status } = result;
-    if (typeof body !== 'string' || (typeof status === 'number' && status >= 400))
+    const { status } = parsed.data;
+    if (status !== undefined && status >= 400)
         return result;
-    let parsed;
+    const body = jsonObject(parsed.data.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) };
+}
+function jsonObject(body) {
     try {
-        parsed = JSON.parse(body);
+        const parsed = z.record(z.string(), z.unknown()).safeParse(JSON.parse(body));
+        return parsed.success ? parsed.data : null;
     }
     catch {
-        return result;
+        return null;
     }
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
-        return result;
-    const record = parsed;
+}
+function pick(body, keys) {
     const picked = {};
     for (const key of keys)
-        if (key in record)
-            picked[key] = record[key];
-    return { ...result, body: JSON.stringify(picked) };
+        if (key in body)
+            picked[key] = body[key];
+    return picked;
 }
 const PLACEHOLDER = /\{(\w+)\}/g;
 function fillTemplate(template, args, defaults) {

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

@@ -0,0 +1,6 @@
+export interface ResponseDecoder {
+    decode: (body: Record<string, unknown>) => Record<string, unknown>;
+}
+export declare const DECODER_NAMES: readonly ['gmail-message'];
+export type DecoderName = (typeof DECODER_NAMES)[number];
+export declare const DECODERS: Record<DecoderName, ResponseDecoder>;

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

@@ -0,0 +1,82 @@
+import b4a from 'b4a';
+import { z } from 'zod';
+import { extractPageText } from '../../web-fetch/extract.js';
+import { decodeHtmlEntities } from '../../web-search/html-helpers.js';
+import { ELISION } from '../http-request/truncate-response.js';
+export const DECODER_NAMES = ['gmail-message'];
+const KEPT_HEADERS = ['From', 'To', 'Subject', 'Date', 'Message-ID', 'References'];
+const MAX_TEXT_CHARS = 4000;
+const PartSchema = z.lazy(() => z.object({
+    mimeType: z.string().optional(),
+    filename: z.string().optional(),
+    headers: z.array(z.object({ name: z.string(), value: z.string() })).optional(),
+    body: z.object({ data: z.string().optional() }).optional(),
+    parts: z.array(PartSchema).optional()
+}));
+const MessageSchema = z.object({
+    id: z.string().optional(),
+    threadId: z.string().optional(),
+    labelIds: z.array(z.string()).optional(),
+    snippet: z.string().optional(),
+    payload: PartSchema.optional()
+});
+const gmailMessage = {
+    decode(body) {
+        const parsed = MessageSchema.safeParse(body);
+        if (!parsed.success)
+            return body;
+        const { id, threadId, labelIds, snippet, payload } = parsed.data;
+        return {
+            id,
+            threadId,
+            labelIds,
+            headers: payload && keptHeaders(payload),
+            snippet: snippet && decodeHtmlEntities(snippet),
+            text: payload && capped(textOf(payload))
+        };
+    }
+};
+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))
+            kept[name] = header.value;
+    }
+    return kept;
+}
+function textOf(part) {
+    const plain = leaves(part, 'text/plain');
+    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)
+        return html.join('\n\n');
+    return undefined;
+}
+function leaves(part, mimeType) {
+    if (part.parts?.length)
+        return part.parts.flatMap((child) => leaves(child, mimeType));
+    if (part.mimeType?.toLowerCase() !== mimeType || part.filename || !part.body?.data)
+        return [];
+    const text = decodeData(part.body.data);
+    return text ? [text] : [];
+}
+function decodeData(data) {
+    try {
+        return b4a.toString(b4a.from(data, 'base64url'), 'utf8').replace(/\r\n/g, '\n').trim();
+    }
+    catch {
+        return '';
+    }
+}
+function capped(text) {
+    if (text === undefined || text.length <= MAX_TEXT_CHARS)
+        return text;
+    return `${text.slice(0, MAX_TEXT_CHARS)}${ELISION}`;
+}
+export const DECODERS = {
+    'gmail-message': gmailMessage
+};