@qvac/harness 0.2.9 → 0.2.10

package/dist/prebuilds-manifest.json

@@ -272,14 +272,6 @@
       "win32-arm64",
       "win32-x64"
     ],
-    "bare-tty/node_modules/bare-signals": [
-      "darwin-arm64",
-      "darwin-x64",
-      "linux-arm64",
-      "linux-x64",
-      "win32-arm64",
-      "win32-x64"
-    ],
     "bare-tty": [
       "darwin-arm64",
       "darwin-x64",

package/dist-lib/lib/capabilities/completion.d.ts

@@ -36,6 +36,7 @@ export interface Agent {
     imageHeight?: number | null;
     approvalMode?: 'ask' | 'skip-all' | null;
     disabledToolsets?: string[] | null;
+    sandboxMode?: boolean | null;
 }
 export interface ImageSettings {
     modelChoice?: string;

package/dist-lib/lib/capabilities/completion.js

@@ -24,7 +24,7 @@ import { collectToolGrants, enabledTools, isSelected, skillIsActive, skillsAreSe
 import { guardToolCall } from '../tools/outbound-guard.js';
 import { isAvailableState } from '../tools/skills/skill-state-constants.js';
 import { resolveImplicitSkill, resolveSkillMention, skillPreloadMessage } from '../tools/skills/mention.js';
-import { permittedTools } from '../tools/toolsets.js';
+import { NETWORK_TOOLSETS, permittedTools } from '../tools/toolsets.js';
 import { promptPrefixHash } from './prompt-prefix.js';
 import { logToolPrompt } from './tool-prompt-log.js';
 import { DIRECT_CALL_ID, loadedSkillFilesFrom, loadedSkillsFrom, TOOL_CONTINUATION_NUDGE, toolResultTurn, withoutSkillLoadTurns } from './tool-turns.js';
@@ -202,7 +202,7 @@ const TOOL_DENIED_MESSAGE = 'The user declined this call. Do not retry it or cal
 function deniedResult() {
     return { error: TOOL_DENIED_MESSAGE, denied: true };
 }
-function denialKey(name, args) {
+function callKey(name, args) {
     try {
         return `${name}:${JSON.stringify(args)}`;
     }
@@ -210,6 +210,34 @@ function denialKey(name, args) {
         return name;
     }
 }
+const RETRYABLE_STATUS = new Set([408, 429]);
+const RETRYABLE_CODE = new Set(['timeout', 'transport', 'busy']);
+function callSucceeded(result, outcome) {
+    if (outcome.kind !== 'success')
+        return false;
+    const exitCode = result?.exitCode;
+    return typeof exitCode !== 'number' || exitCode === 0;
+}
+function retryHints(result) {
+    if (!result || typeof result !== 'object' || Array.isArray(result))
+        return {};
+    const record = result;
+    return {
+        ...(typeof record.status === 'number' ? { status: record.status } : {}),
+        ...(typeof record.code === 'string' ? { code: record.code } : {})
+    };
+}
+function settledFailure(result, outcome) {
+    if (outcome.kind === 'denied' || callSucceeded(result, outcome))
+        return false;
+    if (outcome.kind === 'error' && outcome.error !== undefined)
+        return false;
+    const { code, status } = retryHints(result);
+    if (code !== undefined && RETRYABLE_CODE.has(code))
+        return false;
+    return status === undefined || (status < 500 && !RETRYABLE_STATUS.has(status));
+}
+const MAX_BLOCKED_REPEATS = 3;
 function terminalCall(result, outcome, options) {
     return { result, outcome, executed: options.executed };
 }
@@ -250,7 +278,7 @@ async function executeCall(tool, args, ctx, { approve, signal, denied, sources =
         });
         return blockedResult({ error: refusal, guidance: true }, refusal);
     }
-    const key = denialKey(tool.name, args);
+    const key = callKey(tool.name, args);
     if (denied?.has(key)) {
         hlog('tool denied already, not asking again', { tool: tool.name });
         return deniedCall();
@@ -366,7 +394,7 @@ function blockedSkillMessage(name, catalog, listShown) {
             `skill is available this turn — do not guess another name, and answer from what you ` +
             `already have.`;
 }
-async function resolveToolCalls(toolCalls, enabled, agentId, pipeline, skillNames, signal) {
+async function resolveToolCalls(toolCalls, enabled, agentId, pipeline, skillNames, { sandboxMode, signal }) {
     const resolved = [];
     for (const call of toolCalls) {
         if (signal?.aborted)
@@ -390,6 +418,7 @@ async function resolveToolCalls(toolCalls, enabled, agentId, pipeline, skillName
             agentId,
             skillNames,
             parameters: tool.parameters,
+            sandboxMode,
             signal
         });
         resolved.push(fold.ok
@@ -611,7 +640,10 @@ function* reportUnnamedWrites(said, landed) {
 export async function* completion(sdk, { modelId, acquireRound, model, agent, ctxSize, cacheKey, thinkingDefault, generationParams: generationParamsOverride, responseFormat, messages: storedMessages, tools: allTools = [], skillCatalog = [], approve, attach, fetchAttachment, ragSearch, progress, askUser, signal, toolConfigs, fsRoots = [], fsWriteRoots = [], captureInferenceCalls = false }) {
     const pipeline = new HookPipeline();
     const agentId = agent?.id ?? null;
-    const tools = permittedTools(allTools, agent?.disabledToolsets);
+    const disabledToolsets = agent?.sandboxMode
+        ? [...(agent.disabledToolsets ?? []), ...NETWORK_TOOLSETS]
+        : agent?.disabledToolsets;
+    const tools = permittedTools(allTools, disabledToolsets);
     const writableRoots = [
         ...fsWriteRoots,
         ...fsRoots.filter((root) => root.kind === 'hyper' && root.writable && !fsWriteRoots.includes(root))
@@ -766,6 +798,8 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
         let roundCacheKey = stubDropped ? undefined : visionHistoryCacheKey(cacheKey, history);
         const runUsage = () => usageBreakdown(promptParts, stats.cacheTokens, model);
         const denied = new Set();
+        const failed = new Map();
+        let blockedRepeats = 0;
         let webSearches = 0;
         const sources = trustedSourcesFrom(messages);
         if (preloadedSkill)
@@ -943,7 +977,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
             }
             mute = 0;
             narrated = false;
-            const resolved = await resolveToolCalls(toolCalls, enabled, agent?.id ?? null, pipeline, inContextSkills.map((skill) => skill.name), signal);
+            const resolved = await resolveToolCalls(toolCalls, enabled, agent?.id ?? null, pipeline, inContextSkills.map((skill) => skill.name), { sandboxMode: agent?.sandboxMode === true, signal });
             if (signal?.aborted)
                 throw new AbortedError();
             history = [
@@ -954,10 +988,12 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 }
             ];
             let cappedCalls = 0;
+            let progressed = false;
             runOutcomes.beginRound();
             for (const { call, tool, args, rawCall, rejection, intent } of resolved) {
                 if (signal?.aborted)
                     throw new AbortedError();
+                const priorFailure = failed.get(callKey(call.name, args));
                 const searchCapped = tool?.name === WEB_SEARCH_TOOL_NAME && webSearches >= MAX_WEB_SEARCHES_PER_TURN;
                 const callCtx = {
                     ...toolContext(turnImages, ctxSize),
@@ -975,7 +1011,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 const resource = tool?.resource?.(args) ?? null;
                 const skillName = unquoteArg(args?.name ?? args?.skill_name ?? args?.skill);
                 const skillReloaded = tool?.name === SKILL_TOOL_NAME && !args?.file && loadedThisTurn.has(skillName);
-                const silent = searchCapped || skillReloaded;
+                const silent = searchCapped || skillReloaded || priorFailure !== undefined;
                 const display = silent
                     ? undefined
                     : labelOf(call.name, args, skillCall ? skillEmoji(skillName) : skillIcon);
@@ -989,7 +1025,15 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 const unreadyReason = `skill "${skillName}" is ${unreadyState ?? 'unavailable'} and cannot be used yet. ` +
                     `Tell the user to open it in Skills and finish its setup; do not retry.`;
                 let execution;
-                if (skillReloaded) {
+                if (priorFailure) {
+                    blockedRepeats++;
+                    hlog('repeat of a call that already failed; answered without running it', {
+                        tool: call.name,
+                        blockedRepeats
+                    });
+                    execution = terminalCall(priorFailure.result, priorFailure.outcome, { executed: false });
+                }
+                else if (skillReloaded) {
                     execution = terminalCall({
                         name: skillName,
                         content: `${skillName} is already loaded. Follow the instructions you were given and do not load it again.`
@@ -1037,13 +1081,20 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 });
                 const output = settled.result;
                 const executionOutcome = settled.outcome;
+                if (!priorFailure && settledFailure(output, executionOutcome)) {
+                    failed.set(callKey(call.name, args), settled);
+                }
+                else if (execution.executed && callSucceeded(output, executionOutcome)) {
+                    progressed = true;
+                }
                 runOutcomes.record(output, executionOutcome);
                 if (searchCapped) {
                     cappedCalls++;
                     hlog('web_search capped', { searches: webSearches });
                 }
-                else if (tool?.name === WEB_SEARCH_TOOL_NAME && !rejection)
+                else if (tool?.name === WEB_SEARCH_TOOL_NAME && !rejection && !priorFailure) {
                     webSearches++;
+                }
                 if (call.name === SKILL_TOOL_NAME &&
                     output &&
                     typeof output === 'object' &&
@@ -1095,7 +1146,13 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 history.push({ role: 'tool', content: turn });
             }
             runOutcomes.finishRound();
+            if (progressed) {
+                failed.clear();
+                blockedRepeats = 0;
+            }
             history.push({ role: 'user', content: TOOL_CONTINUATION_NUDGE });
+            if (blockedRepeats >= MAX_BLOCKED_REPEATS)
+                break;
             if (cappedCalls === resolved.length) {
                 if (cappedRounds++ >= MAX_CAPPED_ROUNDS) {
                     outcome = 'search-capped';

package/dist-lib/lib/connect.js

@@ -656,7 +656,8 @@ function knobs(agent) {
         imageWidth: agent.imageWidth ?? undefined,
         imageHeight: agent.imageHeight ?? undefined,
         approvalMode: agent.approvalMode ?? undefined,
-        disabledToolsets: agent.disabledToolsets ?? undefined
+        disabledToolsets: agent.disabledToolsets ?? undefined,
+        sandboxMode: agent.sandboxMode ?? undefined
     };
 }
 async function bridgeAttach(event, attach) {

package/dist-lib/lib/contract-types.d.ts

@@ -38,6 +38,7 @@ export interface AgentKnobs {
     imageHeight?: number | null;
     approvalMode?: 'ask' | 'skip-all' | null;
     disabledToolsets?: string[] | null;
+    sandboxMode?: boolean | null;
 }
 export interface CompletionContext {
     model: string;

package/dist-lib/lib/docx/index.js

@@ -1,9 +1,5 @@
-import b4a from 'b4a';
-import fs from 'fs';
-import { runPython } from '../tools/exec/adapters/python/pyodide.js';
-import { planVendoredInstall, vendoredManifest, wheelsDir } from '../tools/exec/adapters/python/wheels.js';
+import { extractWithPython } from '../office/python.js';
 export { closePythonWorker as closeDocxWorker } from '../tools/exec/adapters/python/worker/client.js';
-const MAX_OFFICE_BYTES = 20 * 1024 * 1024;
 const PACKAGES = ['python-docx==1.2.0'];
 const EXTRACT = `from docx import Document
 from docx.text.paragraph import Paragraph
@@ -21,29 +17,10 @@ def text(container):
 Path("extracted.txt").write_text("\\n".join(text(Document("input.docx"))), encoding="utf-8")
 `;
 export async function extractDocxText(bytes, fileName, options = {}) {
-    if (bytes.byteLength > MAX_OFFICE_BYTES) {
-        throw new Error(`document is too large to extract: ${bytes.byteLength} bytes, limit ${MAX_OFFICE_BYTES}`);
-    }
-    const dir = wheelsDir();
-    const manifest = vendoredManifest(dir);
-    const install = planVendoredInstall(PACKAGES, { dir, manifest });
-    if (!dir ||
-        !manifest ||
-        !install ||
-        !['micropip', ...install.packages].every((name) => Object.keys(manifest.files).some((file) => file.replaceAll('_', '-').startsWith(`${name}-`) && fs.existsSync(`${dir}/${file}`)))) {
-        throw new Error('bundled DOCX extraction packages are unavailable');
-    }
-    const result = await runPython(EXTRACT, {
+    return extractWithPython(bytes, fileName, {
+        format: 'DOCX',
         packages: PACKAGES,
-        inputs: [{ path: 'input.docx', bytes }],
-        outputs: ['extracted.txt'],
+        source: EXTRACT,
         signal: options.signal
     });
-    if (result.exitCode !== 0)
-        throw new Error(`${fileName}: ${result.stderr.trim()}`);
-    const output = result.files?.get('extracted.txt');
-    if (!output) {
-        throw new Error(result.rejected?.[0]?.reason ?? 'DOCX extraction produced no text file');
-    }
-    return b4a.toString(output, 'utf8');
 }

package/dist-lib/lib/hooks/built-in/index.d.ts

@@ -1,3 +1,4 @@
 export { ArgRepairHook } from './arg-repair.ts';
 export { EgressGuardHook } from './egress.ts';
+export { SandboxHook } from './sandbox.ts';
 export { SkillCatalogGuardHook } from './skill-catalog.ts';

package/dist-lib/lib/hooks/built-in/index.js

@@ -1,3 +1,4 @@
 export { ArgRepairHook } from './arg-repair.js';
 export { EgressGuardHook } from './egress.js';
+export { SandboxHook } from './sandbox.js';
 export { SkillCatalogGuardHook } from './skill-catalog.js';

package/dist-lib/lib/hooks/built-in/sandbox.d.ts

@@ -0,0 +1,5 @@
+import type { HarnessHook, HookContext, HookResult } from '../types.ts';
+export declare class SandboxHook implements HarnessHook {
+    readonly phase: 'preToolCall';
+    run(ctx: HookContext): HookResult;
+}

package/dist-lib/lib/hooks/built-in/sandbox.js

@@ -0,0 +1,43 @@
+import { bareBin, firstCommandToken } from '../../tools/exec/scope.js';
+const NETWORK_BINS = new Set([
+    'curl',
+    'wget',
+    'nc',
+    'ncat',
+    'netcat',
+    'ssh',
+    'scp',
+    'sftp',
+    'rsync',
+    'ftp',
+    'telnet',
+    'git',
+    'npm',
+    'npx',
+    'pnpm',
+    'yarn',
+    'bun',
+    'pip',
+    'pip3',
+    'brew',
+    'dig',
+    'nslookup',
+    'ping',
+    'openssl'
+]);
+export class SandboxHook {
+    phase = 'preToolCall';
+    run(ctx) {
+        if (ctx.phase !== 'preToolCall')
+            return;
+        if (!ctx.sandboxMode || ctx.toolName !== 'exec')
+            return;
+        if (Array.isArray(ctx.args.packages) && ctx.args.packages.length) {
+            return { error: 'sandbox mode: installing packages reaches the network', guidance: true };
+        }
+        const bin = bareBin(firstCommandToken(String(ctx.args.command ?? '')).replace(/^.*[/\\]/, ''));
+        if (bin && NETWORK_BINS.has(bin)) {
+            return { error: `sandbox mode: ${bin} reaches the network`, guidance: true };
+        }
+    }
+}

package/dist-lib/lib/hooks/built-in/skill-catalog.js

@@ -11,7 +11,12 @@ export class SkillCatalogGuardHook {
         const known = new Set(entries.map((entry) => (typeof entry === 'string' ? entry : entry.name)));
         const raw = ctx.args.name ?? ctx.args.skill_name ?? ctx.args.skill;
         const name = typeof raw === 'string' ? raw : '';
-        if (!known.has(name))
-            return { error: `skill not found: ${name}`, guidance: true };
+        if (known.has(name))
+            return;
+        const listed = [...known].join(', ');
+        const rest = listed
+            ? `The only skills are: ${listed}. Nothing else needs a skill load — answer or act with the tools you already have.`
+            : 'No skill is available this turn — answer or act with the tools you already have.';
+        return { error: `skill not found: ${name}. ${rest}`, guidance: true };
     }
 }

package/dist-lib/lib/hooks/registry.js

@@ -1,6 +1,7 @@
-import { ArgRepairHook, EgressGuardHook, SkillCatalogGuardHook } from './built-in/index.js';
+import { ArgRepairHook, EgressGuardHook, SandboxHook, SkillCatalogGuardHook } from './built-in/index.js';
 export const harnessHooks = [
     new ArgRepairHook(),
     new EgressGuardHook(),
+    new SandboxHook(),
     new SkillCatalogGuardHook()
 ];

package/dist-lib/lib/hooks/types.d.ts

@@ -14,6 +14,7 @@ export interface PreToolCallPayload {
     readonly signal?: BareAbortSignal | undefined;
     readonly skillNames?: readonly string[];
     readonly parameters?: ToolDefinition['parameters'];
+    readonly sandboxMode?: boolean;
     args: Record<string, unknown>;
 }
 export interface PostToolCallPayload {

package/dist-lib/lib/office/index.d.ts

@@ -0,0 +1,6 @@
+import type { AbortSignal } from 'bare-abort-controller';
+export { closePythonWorker as closeOfficeWorker } from '../tools/exec/adapters/python/worker/client.ts';
+export declare function extractOfficeText(bytes: Uint8Array, fileName: string, options?: {
+    readonly signal?: AbortSignal | undefined;
+    readonly mimeType?: string | undefined;
+}): Promise<string>;

package/dist-lib/lib/office/index.js

@@ -0,0 +1,38 @@
+import path from 'path';
+import { extractDocxText } from '../docx/index.js';
+import { extractWithPython } from './python.js';
+import { XLSX_EXTRACT } from './xlsx.js';
+import { PPTX_EXTRACT } from './pptx.js';
+export { closePythonWorker as closeOfficeWorker } from '../tools/exec/adapters/python/worker/client.js';
+const OFFICE_MIME_EXTENSIONS = {
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx'
+};
+export async function extractOfficeText(bytes, fileName, options = {}) {
+    const mimeType = options.mimeType?.split(';')[0]?.trim().toLowerCase();
+    const suffix = path.extname(fileName).toLowerCase();
+    const extension = ['.docx', '.xlsx', '.pptx'].includes(suffix)
+        ? suffix
+        : OFFICE_MIME_EXTENSIONS[mimeType ?? ''];
+    if (extension === '.docx') {
+        return extractDocxText(bytes, fileName, options);
+    }
+    if (extension === '.xlsx') {
+        return extractWithPython(bytes, fileName, {
+            format: 'XLSX',
+            packages: ['openpyxl==3.1.5'],
+            source: XLSX_EXTRACT,
+            signal: options.signal
+        });
+    }
+    if (extension === '.pptx') {
+        return extractWithPython(bytes, fileName, {
+            format: 'PPTX',
+            packages: ['python-pptx==1.0.2'],
+            source: PPTX_EXTRACT,
+            signal: options.signal
+        });
+    }
+    throw new Error(`Unsupported Office document: ${fileName}`);
+}

package/dist-lib/lib/office/pptx.d.ts

@@ -0,0 +1 @@
+export declare const PPTX_EXTRACT: string;

package/dist-lib/lib/office/pptx.js

@@ -0,0 +1,26 @@
+export const PPTX_EXTRACT = `from pptx import Presentation
+from pptx.enum.shapes import MSO_SHAPE_TYPE
+from pathlib import Path
+
+def text(shapes):
+    for shape in shapes:
+        if shape.shape_type == MSO_SHAPE_TYPE.GROUP:
+            yield from text(shape.shapes)
+        elif shape.has_text_frame:
+            if shape.text.strip():
+                yield shape.text
+        elif shape.has_table:
+            for row in shape.table.rows:
+                cells = ["" if cell.is_spanned else cell.text.replace("\\n", " ") for cell in row.cells]
+                if any(cell.strip() for cell in cells):
+                    yield " | ".join(cells)
+
+with Path("extracted.txt").open("w", encoding="utf-8") as output:
+    for number, slide in enumerate(Presentation("input.pptx").slides, 1):
+        heading = False
+        for block in text(slide.shapes):
+            if not heading:
+                output.write("Slide " + str(number) + "\\n")
+                heading = True
+            output.write(block + "\\n")
+`;

package/dist-lib/lib/office/python.d.ts

@@ -0,0 +1,7 @@
+import type { AbortSignal } from 'bare-abort-controller';
+export declare function extractWithPython(bytes: Uint8Array, fileName: string, { format, packages, source, signal }: {
+    readonly format: string;
+    readonly packages: readonly string[];
+    readonly source: string;
+    readonly signal?: AbortSignal | undefined;
+}): Promise<string>;

package/dist-lib/lib/office/python.js

@@ -0,0 +1,32 @@
+import b4a from 'b4a';
+import fs from 'fs';
+import { runPython } from '../tools/exec/adapters/python/pyodide.js';
+import { planVendoredInstall, vendoredManifest, wheelsDir } from '../tools/exec/adapters/python/wheels.js';
+const MAX_OFFICE_BYTES = 20 * 1024 * 1024;
+export async function extractWithPython(bytes, fileName, { format, packages, source, signal }) {
+    if (bytes.byteLength > MAX_OFFICE_BYTES) {
+        throw new Error(`document is too large to extract: ${bytes.byteLength} bytes, limit ${MAX_OFFICE_BYTES}`);
+    }
+    const dir = wheelsDir();
+    const manifest = vendoredManifest(dir);
+    const install = planVendoredInstall(packages, { dir, manifest });
+    if (!dir ||
+        !manifest ||
+        !install ||
+        !['micropip', ...install.packages].every((name) => Object.keys(manifest.files).some((file) => file.replaceAll('_', '-').startsWith(`${name}-`) && fs.existsSync(`${dir}/${file}`)))) {
+        throw new Error(`bundled ${format} extraction packages are unavailable`);
+    }
+    const result = await runPython(source, {
+        packages,
+        inputs: [{ path: `input.${format.toLowerCase()}`, bytes }],
+        outputs: ['extracted.txt'],
+        signal
+    });
+    if (result.exitCode !== 0)
+        throw new Error(`${fileName}: ${result.stderr.trim()}`);
+    const output = result.files?.get('extracted.txt');
+    if (!output) {
+        throw new Error(result.rejected?.[0]?.reason ?? `${format} extraction produced no text file`);
+    }
+    return b4a.toString(output, 'utf8');
+}

package/dist-lib/lib/office/xlsx.d.ts

@@ -0,0 +1 @@
+export declare const XLSX_EXTRACT: string;

package/dist-lib/lib/office/xlsx.js

@@ -0,0 +1,26 @@
+export const XLSX_EXTRACT = `from openpyxl import load_workbook
+from pathlib import Path
+
+formulas = load_workbook("input.xlsx", read_only=True, data_only=False, keep_links=False)
+values = load_workbook("input.xlsx", read_only=True, data_only=True, keep_links=False)
+try:
+    with Path("extracted.txt").open("w", encoding="utf-8") as output:
+        for sheet in formulas.worksheets:
+            heading = False
+            cached = values[sheet.title]
+            sheet.reset_dimensions()
+            cached.reset_dimensions()
+            for cells, results in zip(sheet.iter_rows(), cached.iter_rows()):
+                row = [result.value if cell.data_type == "f" and result.value is not None else cell.value
+                       for cell, result in zip(cells, results)]
+                if not any(value is not None and str(value).strip() for value in row):
+                    continue
+                if not heading:
+                    output.write("Sheet: " + sheet.title + "\\n")
+                    heading = True
+                output.write(" | ".join("" if value is None else str(value).replace("\\n", " ")
+                                        for value in row) + "\\n")
+finally:
+    formulas.close()
+    values.close()
+`;

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

@@ -170,7 +170,7 @@ export function createEditImageTool(runtime, { loadMedia = defaultLoadMedia, res
             if (sources.length > 1 && !inContext)
                 return { error: MULTI_SOURCE_UNSUPPORTED };
             if (!runtime.acquire())
-                return { error: BUSY_ERROR };
+                return { error: BUSY_ERROR, code: 'busy' };
             const report = ctx.progress;
             const onTick = report && generationPercentTick((percentage) => report({ percentage }), sources.length);
             try {

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

@@ -323,7 +323,7 @@ export function createGenerateImageTool(runtime, clamps) {
             if (!ctx?.attach)
                 return { error: 'this device cannot persist generated images' };
             if (!runtime.acquire())
-                return { error: BUSY_ERROR };
+                return { error: BUSY_ERROR, code: 'busy' };
             const report = ctx.progress;
             const onTick = report && generationPercentTick((percentage) => report({ percentage }));
             try {

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

@@ -443,7 +443,7 @@ export function createGenerateMusicTool(runtime, clamps) {
             if (!ctx?.attach)
                 return { error: 'this device cannot persist generated audio' };
             if (!runtime.acquire())
-                return { error: BUSY_ERROR };
+                return { error: BUSY_ERROR, code: 'busy' };
             const report = ctx.progress;
             const onTick = report && musicPercentTick((percentage) => report({ percentage }));
             const capMax = stepsCap ?? MAX_STEPS;

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

@@ -163,10 +163,10 @@ export function createHttpRequestTool({ fetch: fetchImpl, credentialStore, crede
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
+                const timedOut = error.name === 'AbortError' || error instanceof AbortedError;
                 return {
-                    error: error.name === 'AbortError' || error instanceof AbortedError
-                        ? 'request timed out'
-                        : `request failed: ${error.message}`
+                    error: timedOut ? 'request timed out' : `request failed: ${error.message}`,
+                    code: timedOut ? 'timeout' : 'transport'
                 };
             }
             finally {

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

@@ -141,10 +141,10 @@ export function createMcpCallTool({ fetch: fetchImpl, credentialStore, credentia
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
+                const timedOut = error.name === 'AbortError' || error instanceof AbortedError;
                 return {
-                    error: error.name === 'AbortError' || error instanceof AbortedError
-                        ? 'request timed out'
-                        : `request failed: ${error.message}`
+                    error: timedOut ? 'request timed out' : `request failed: ${error.message}`,
+                    code: timedOut ? 'timeout' : 'transport'
                 };
             }
             finally {

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

@@ -131,8 +131,10 @@ export function createSkillTool({ skillsDir, overlayDir = resolveSkillsOverlayDi
                 if (file === MAIN_FILE)
                     return { error: `skill not found: ${name}` };
                 const available = await listSkillFiles([overlayDrive, baseDrive], name);
-                const listing = available.length ? ` — files this skill has: ${available.join(', ')}` : '';
-                return { error: `file not found in skill ${name}: ${file}${listing}` };
+                const rest = available.length
+                    ? ` — files this skill has: ${available.join(', ')}`
+                    : '. This skill has no other files; you already have its full instructions — act now.';
+                return { error: `file not found in skill ${name}: ${file}${rest}` };
             }
         }
     };

package/dist-lib/lib/tools/skills/auth-resolver.d.ts

@@ -19,6 +19,7 @@ export declare function isCredentialUrlAllowed(target: string, patterns: readonl
 export type CredentialAllowListFn = (ctx?: ToolExecuteContext) => CredentialAllowList;
 export type AuthOutcome = {
     readonly token: string;
+    readonly key: string;
 } | {
     readonly error: string;
 };