@qvac/harness 0.3.0 → 0.3.2

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

@@ -2,12 +2,15 @@ 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 { namedHosts } from './exec/adapters/python/named-hosts.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 +67,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)
@@ -80,6 +83,34 @@ function checkFileArgs(args, python) {
 function truncateLabel(text) {
     return text.length > 120 ? `${text.slice(0, 120)}…` : text;
 }
+const CONNECT_ANSWER_MS = 60_000;
+function connectAsker(askUser) {
+    return async (host) => {
+        let timer;
+        const late = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), CONNECT_ANSWER_MS);
+        });
+        try {
+            const answer = await Promise.race([
+                askUser({
+                    question: `This Python run wants to connect to ${host}, which its approved code does not name. Allow it for this run?`,
+                    options: ['Allow', 'Deny']
+                }),
+                late
+            ]);
+            return /^allow/i.test((answer ?? '').trim());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+function networkPrefix(source) {
+    const hosts = namedHosts(source);
+    if (hosts.length === 0)
+        return ' · network: no host named in the code';
+    return ` · network: ${hosts.join(', ')}`;
+}
 function packageSuffix(args) {
     if (!Array.isArray(args.packages) || args.packages.length === 0)
         return '';
@@ -100,13 +131,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 +250,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 +284,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 +399,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 +412,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 +453,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, ctx) {
+            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) };
@@ -414,8 +467,10 @@ export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide
             if (!command)
                 return null;
             const workdir = typeof args.workdir === 'string' && args.workdir.trim() ? args.workdir.trim() : null;
+            const source = unwrapPythonSource(command) ?? command;
+            const online = pythonNetwork && ctx?.sandboxMode !== true;
             const body = runsThroughPyodide(args.language, disablePyodide)
-                ? `python${packageSuffix(args)}${fileSuffix(args)}: ${(unwrapPythonSource(command) ?? command).slice(0, 120)}`
+                ? `python${online ? networkPrefix(source) : ''}${packageSuffix(args)}${fileSuffix(args)}: ${source.slice(0, 120)}`
                 : command;
             return {
                 kind: 'command',
@@ -426,11 +481,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 +544,11 @@ 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,
+                    approval: ctx?.approval,
+                    confirmConnect: ctx?.askUser ? connectAsker(ctx.askUser) : undefined
                 });
                 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
+};

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

@@ -1,5 +1,12 @@
 import { z } from 'zod';
 import type { ToolParameters } from '../../capabilities/completion.ts';
+declare const ResponseSchema: z.ZodUnion<readonly [z.ZodObject<{
+    pick: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    decode: z.ZodEnum<{
+        "gmail-message": "gmail-message";
+    }>;
+}, z.core.$strict>]>;
 declare const OperationSchema: z.ZodObject<{
     tool: z.ZodString;
     description: z.ZodString;
@@ -16,6 +23,7 @@ declare const OperationSchema: z.ZodObject<{
             "drive-create-folder": "drive-create-folder";
             "drive-trash": "drive-trash";
             "gmail-draft": "gmail-draft";
+            "gmail-get": "gmail-get";
             "gmail-send": "gmail-send";
             "notion-create-page": "notion-create-page";
             "notion-insert-content": "notion-insert-content";
@@ -43,6 +51,7 @@ declare const OperationSchema: z.ZodObject<{
             "drive-create-folder": "drive-create-folder";
             "drive-trash": "drive-trash";
             "gmail-draft": "gmail-draft";
+            "gmail-get": "gmail-get";
             "gmail-send": "gmail-send";
             "notion-create-page": "notion-create-page";
             "notion-insert-content": "notion-insert-content";
@@ -51,10 +60,15 @@ declare const OperationSchema: z.ZodObject<{
             "sheets-write-values": "sheets-write-values";
         }>;
     }, z.core.$strip>]>;
-    response: z.ZodOptional<z.ZodObject<{
+    response: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         pick: z.ZodArray<z.ZodString>;
-    }, z.core.$strip>>;
+    }, z.core.$strict>, z.ZodObject<{
+        decode: z.ZodEnum<{
+            "gmail-message": "gmail-message";
+        }>;
+    }, z.core.$strict>]>>;
 }, z.core.$strip>;
 export type OperationSpec = z.infer<typeof OperationSchema>;
+export type OperationResponse = z.infer<typeof ResponseSchema>;
 export declare function parseOperationsManifest(json: string): OperationSpec[] | null;
 export {};

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { BUILDER_NAMES } from './builders.js';
+import { DECODER_NAMES } from './decoders.js';
 const ParameterType = z.enum(['string', 'number', 'boolean', 'object', 'integer', 'array', 'null']);
 const ParameterSchema = z.lazy(() => z.object({
     type: z.union([ParameterType, z.array(ParameterType).min(1)]),
@@ -29,12 +30,16 @@ const McpRequestSchema = z.object({
     builder: z.enum(BUILDER_NAMES)
 });
 const RequestSchema = z.union([McpRequestSchema, HttpRequestSchema]);
+const ResponseSchema = z.union([
+    z.strictObject({ pick: z.array(z.string().min(1)).min(1) }),
+    z.strictObject({ decode: z.enum(DECODER_NAMES) })
+]);
 const OperationSchema = z.object({
     tool: z.string().min(1),
     description: z.string().min(1),
     parameters: ParametersSchema,
     request: RequestSchema,
-    response: z.object({ pick: z.array(z.string().min(1)).min(1) }).optional()
+    response: ResponseSchema.optional()
 });
 const ManifestSchema = z.object({ operations: z.array(OperationSchema) });
 export function parseOperationsManifest(json) {

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

@@ -1,6 +1,9 @@
 import type { ToolDefinition } from '../capabilities/completion.ts';
 import { type CredentialStoreFn } from './skills/auth-resolver.ts';
 export type ReadSkillFn = (name: string, file: string) => Promise<string> | string;
+export declare function mainFileRequested(name: string, file: unknown): boolean;
+export declare function skillFileArg(args: Record<string, unknown> | null | undefined): unknown;
+export declare function skillFileStem(file: string): string;
 export interface SkillToolOptions {
     skillsDir?: string;
     overlayDir?: string | null;

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

@@ -10,6 +10,25 @@ import { parseToolGrant } from './skills/tool-grants.js';
 import { shellEscapeArg } from './exec/shell-argv.js';
 import { isObsidianVaultPath, OBSIDIAN_SKILL_NAME, OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY } from './skills/obsidian-readiness.js';
 const MAIN_FILE = 'SKILL.md';
+const NO_FILE = /^(?:none|null|undefined|main)$/i;
+export function mainFileRequested(name, file) {
+    if (file === undefined || file === null)
+        return true;
+    const asked = unquoteArg(file).toLowerCase();
+    return (asked === '' ||
+        NO_FILE.test(asked) ||
+        asked === name.toLowerCase() ||
+        asked === MAIN_FILE.toLowerCase());
+}
+export function skillFileArg(args) {
+    return args?.file ?? args?.path ?? args?.filename;
+}
+export function skillFileStem(file) {
+    return file
+        .toLowerCase()
+        .replace(/^references\//, '')
+        .replace(/\.md$/, '');
+}
 function resolveSkillDir(root, name) {
     if (!root)
         return null;
@@ -47,6 +66,10 @@ async function listSkillFiles(drives, name) {
     }
     return [...files].sort();
 }
+function nearestFile(wanted, available) {
+    const matches = available.filter((file) => skillFileStem(file) === skillFileStem(wanted));
+    return matches.length === 1 ? matches[0] : null;
+}
 async function vaultModeNote(name, credentialStore, ctx) {
     if (name !== OBSIDIAN_SKILL_NAME || !credentialStore)
         return null;
@@ -107,13 +130,13 @@ export function createSkillTool({ skillsDir, overlayDir = resolveSkillsOverlayDi
         autoApprove: true,
         async execute(args, ctx) {
             const name = unquoteArg(args.name ?? args.skill_name ?? args.skill);
-            const fileArg = args.file ?? args.path ?? args.filename;
-            const file = fileArg === undefined || fileArg === null ? MAIN_FILE : unquoteArg(fileArg);
+            const fileArg = skillFileArg(args);
+            const file = mainFileRequested(name, fileArg) ? MAIN_FILE : unquoteArg(fileArg);
             if (file.startsWith('/') || file.includes('\\') || file.split('/').includes('..')) {
                 return { error: `file not found in skill ${name}: ${file}` };
             }
-            try {
-                const { raw, root } = await resolveSkill(name, file === '' ? MAIN_FILE : file);
+            const load = async (target) => {
+                const { raw, root } = await resolveSkill(name, target);
                 const { body, meta } = parseSkillFrontMatter(raw);
                 const dir = resolveSkillDir(root, name);
                 const content = dir ? body.replaceAll('{{SKILL_DIR}}', shellEscapeArg(dir)) : body;
@@ -123,14 +146,24 @@ export function createSkillTool({ skillsDir, overlayDir = resolveSkillsOverlayDi
                 ].filter(Boolean);
                 return {
                     name,
-                    file: file === MAIN_FILE || file === '' ? undefined : file,
+                    file: target === MAIN_FILE ? undefined : target,
                     content: notes.length ? [content.trim(), ...notes].join('\n\n') : content
                 };
+            };
+            try {
+                return await load(file);
             }
             catch {
                 if (file === MAIN_FILE)
                     return { error: `skill not found: ${name}` };
                 const available = await listSkillFiles([overlayDrive, baseDrive], name);
+                const near = nearestFile(file, available);
+                if (near !== null) {
+                    try {
+                        return await load(near);
+                    }
+                    catch { }
+                }
                 const rest = available.length
                     ? ` — files this skill has: ${available.join(', ')}`
                     : '. This skill has no other files; you already have its full instructions — act now.';