@qvac/harness 0.2.8 → 0.2.10

package/dist-lib/index.d.ts

@@ -93,6 +93,7 @@ export interface CompletionContext {
     toolConfigs?: Record<string, Record<string, unknown>>;
     generationParams?: LlmGenerationParams;
     responseFormat?: ResponseFormat;
+    captureInferenceCalls?: boolean;
     grantedDirs?: string[];
     grantedDrives?: GrantedDrive[];
     driveOp?: DriveOpFn;
@@ -239,7 +240,7 @@ export declare class Harness extends ReadyResource {
         agent?: Agent;
         signal?: BareAbortSignal;
     }): Promise<void>;
-    completion({ model, agent, messages, cacheKey, thinkingDefault, toolConfigs, generationParams, responseFormat, grantedDirs, grantedDrives, driveOp, grantedWriteDirs, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal }: CompletionContext): AsyncGenerator<CompletionEvent>;
+    completion({ model, agent, messages, cacheKey, thinkingDefault, toolConfigs, generationParams, responseFormat, captureInferenceCalls, grantedDirs, grantedDrives, driveOp, grantedWriteDirs, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal }: CompletionContext): AsyncGenerator<CompletionEvent>;
     private _makeRoomForCompletion;
     private _evictWedgedModel;
     private _evictAfterLeases;

package/dist-lib/index.js

@@ -943,7 +943,7 @@ export class Harness extends ReadyResource {
             releaseModel(pool, key);
         }
     }
-    async *completion({ model, agent, messages, cacheKey, thinkingDefault, toolConfigs, generationParams, responseFormat, grantedDirs, grantedDrives, driveOp, grantedWriteDirs, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal }) {
+    async *completion({ model, agent, messages, cacheKey, thinkingDefault, toolConfigs, generationParams, responseFormat, captureInferenceCalls, grantedDirs, grantedDrives, driveOp, grantedWriteDirs, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal }) {
         await this.ready();
         if (this.suspended)
             throw new Error('harness is suspended');
@@ -1016,6 +1016,7 @@ export class Harness extends ReadyResource {
                 thinkingDefault,
                 generationParams,
                 responseFormat,
+                captureInferenceCalls,
                 messages: turns,
                 tools: this._tools,
                 skillCatalog: await this._completionSkills(agent?.id ?? null, model),

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;
@@ -221,8 +222,40 @@ export type MetricsEvent = {
     ctxSize?: number | undefined;
     backends?: RunBackendUse[] | undefined;
     usage?: UsageBreakdown | undefined;
+    stopReason?: string | undefined;
 };
-export type CompletionEvent = TextEvent | ToolCallEvent | ToolResultEvent | ToolActivityEvent | ErrorEvent | AbortedEvent | MetricsEvent;
+export interface InferenceCall {
+    round: number;
+    droppedTurns: number;
+    modelId: string;
+    messages: Message[];
+    tools: SdkTool[] | undefined;
+    generationParams: LlmGenerationParams | undefined;
+    responseFormat: ResponseFormat | undefined;
+    toolDialect: ToolDialect | undefined;
+    cacheKey: string | undefined;
+    promptPrefix: string;
+}
+export type InferenceCallEvent = {
+    type: 'inference-call';
+    call: InferenceCall;
+};
+export type InferenceSentEvent = {
+    type: 'inference-sent';
+    round: number;
+    droppedTurns: number;
+    messages: Message[] | undefined;
+    tokens: InferenceTokens | undefined;
+    outcome: 'completed' | 'overflowed' | 'failed';
+    reason: string | undefined;
+};
+export interface InferenceTokens {
+    prompt?: number | undefined;
+    generated?: number | undefined;
+    cached?: number | undefined;
+    timeToFirstToken?: number | undefined;
+}
+export type CompletionEvent = TextEvent | ToolCallEvent | ToolResultEvent | ToolActivityEvent | ErrorEvent | AbortedEvent | MetricsEvent | InferenceCallEvent | InferenceSentEvent;
 export interface CompletionSdkResult {
     requestId?: string;
     tokenStream: AsyncIterable<string>;
@@ -283,6 +316,7 @@ interface CompletionArgs {
     toolConfigs?: Record<string, Record<string, unknown>>;
     fsRoots?: readonly DriveRoot[];
     fsWriteRoots?: readonly DriveRoot[];
+    captureInferenceCalls?: boolean;
 }
 export declare const CONTEXT_OVERFLOW_MESSAGE = "This message is too large for the model context window.";
 export declare function trustedSourcesFrom(history: readonly Message[]): TrustedSource[];
@@ -290,5 +324,5 @@ export declare function toSdkTool(tool: ToolDefinition): SdkTool;
 export type CompletionSkillEntry = SkillCatalogEntry & {
     readonly status?: SkillState;
 };
-export declare function completion(sdk: CompletionSdk, { 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 }: CompletionArgs): AsyncGenerator<CompletionEvent>;
+export declare function completion(sdk: CompletionSdk, { 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 }: CompletionArgs): AsyncGenerator<CompletionEvent>;
 export {};

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';
@@ -157,7 +157,8 @@ function preloadLastUser(messages, name, body) {
     }
     return messages;
 }
-function collectStats(state, stats) {
+function collectStats(state, stats, stopReason) {
+    state.stopReason = stopReason;
     if (!stats)
         return;
     if (state.ttft === undefined && stats.timeToFirstToken)
@@ -191,7 +192,8 @@ function metricsEvent(state, usage) {
         cacheTokens: state.cacheTokens,
         ...(state.ctxSize ? { ctxSize: state.ctxSize } : {}),
         ...(state.backends.length ? { backends: state.backends } : {}),
-        ...(usage ? { usage } : {})
+        ...(usage ? { usage } : {}),
+        ...(state.stopReason ? { stopReason: state.stopReason } : {})
     };
 }
 const TOOL_DENIED_MESSAGE = 'The user declined this call. Do not retry it or call it with different arguments to get ' +
@@ -200,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)}`;
     }
@@ -208,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 };
 }
@@ -248,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();
@@ -364,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)
@@ -388,6 +418,7 @@ async function resolveToolCalls(toolCalls, enabled, agentId, pipeline, skillName
             agentId,
             skillNames,
             parameters: tool.parameters,
+            sandboxMode,
             signal
         });
         resolved.push(fold.ok
@@ -463,6 +494,21 @@ async function* runRoundTokens(sdk, result, state, signal, startInThink = false)
         await events.return(null);
     }
 }
+function sentMessages(stats) {
+    const sent = stats?.sentMessages;
+    return Array.isArray(sent) ? sent : null;
+}
+function roundTokens(stats) {
+    if (!stats)
+        return undefined;
+    const tokens = {
+        prompt: stats.promptTokens,
+        generated: stats.generatedTokens,
+        cached: stats.cacheTokens,
+        timeToFirstToken: stats.timeToFirstToken
+    };
+    return Object.values(tokens).some((value) => value !== undefined) ? tokens : undefined;
+}
 const TRUNCATED_FINAL_MS = 2000;
 function truncatedFinal(final, contentText) {
     const accepted = { contentText, toolCalls: [], raw: { fullText: contentText } };
@@ -496,17 +542,35 @@ async function* runRecoveredRoundWith(sdk, args, modelId) {
         let emitted = false;
         const state = { stopToken: null, unproven: null, rawContentText: '' };
         const cacheable = candidate.history === args.history;
+        const params = {
+            modelId,
+            history: projectVisionHistory(candidate.history),
+            stream: true,
+            tools: args.tools,
+            generationParams: args.generationParams,
+            responseFormat: args.responseFormat,
+            toolDialect: args.toolDialect,
+            kvCache: cacheable ? args.cacheKey : undefined
+        };
+        if (args.capture) {
+            yield {
+                type: 'inference-call',
+                call: {
+                    round: args.round,
+                    droppedTurns: candidate.droppedTurns,
+                    modelId,
+                    messages: params.history,
+                    tools: params.tools,
+                    generationParams: params.generationParams,
+                    responseFormat: params.responseFormat,
+                    toolDialect: params.toolDialect,
+                    cacheKey: params.kvCache,
+                    promptPrefix: args.promptPrefix
+                }
+            };
+        }
         try {
-            const result = sdk.completion({
-                modelId,
-                history: projectVisionHistory(candidate.history),
-                stream: true,
-                tools: args.tools,
-                generationParams: args.generationParams,
-                ...(args.responseFormat ? { responseFormat: args.responseFormat } : {}),
-                toolDialect: args.toolDialect,
-                ...(cacheable && args.cacheKey ? { kvCache: args.cacheKey } : {})
-            });
+            const result = sdk.completion(params);
             result.final.catch(noop);
             const startInThink = args.generationParams?.reasoning_budget === -1;
             for await (const event of runRoundTokens(sdk, result, state, args.signal, startInThink)) {
@@ -518,6 +582,17 @@ async function* runRecoveredRoundWith(sdk, args, modelId) {
             const final = state.stopToken
                 ? await truncatedFinal(result.final, state.rawContentText)
                 : await raceAbort(result.final, args.signal);
+            if (args.capture) {
+                yield {
+                    type: 'inference-sent',
+                    round: args.round,
+                    droppedTurns: candidate.droppedTurns,
+                    messages: sentMessages(final.stats) ?? undefined,
+                    tokens: roundTokens(final.stats),
+                    outcome: 'completed',
+                    reason: undefined
+                };
+            }
             const replay = unprovenReplay(state, final);
             hlog('final', {
                 stopReason: final.stopReason,
@@ -535,6 +610,17 @@ async function* runRecoveredRoundWith(sdk, args, modelId) {
             };
         }
         catch (err) {
+            if (args.capture) {
+                yield {
+                    type: 'inference-sent',
+                    round: args.round,
+                    droppedTurns: candidate.droppedTurns,
+                    messages: undefined,
+                    tokens: undefined,
+                    outcome: isContextOverflowError(err) ? 'overflowed' : 'failed',
+                    reason: err instanceof Error ? err.message : String(err)
+                };
+            }
             if (!isContextOverflowError(err))
                 throw err;
             if (emitted)
@@ -551,10 +637,13 @@ function* reportUnnamedWrites(said, landed) {
     if (unreported)
         yield { type: 'content', text: unreported };
 }
-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 = [] }) {
+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))
@@ -709,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)
@@ -789,7 +880,9 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
         let mute = 0;
         let narrated = false;
         let cappedRounds = 0;
-        for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+        let roundsSent = 0;
+        let round = 0;
+        for (; round < MAX_TOOL_ROUNDS; round++) {
             if (signal?.aborted)
                 throw new AbortedError();
             if (Date.now() >= runBudget.deadlineMs) {
@@ -820,13 +913,17 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 responseFormat,
                 toolDialect,
                 cacheKey: roundCacheKey,
-                signal
+                signal,
+                round,
+                promptPrefix,
+                capture: captureInferenceCalls
             });
+            roundsSent = round + 1;
             const final = recovered.final;
             if (!recovered.cacheable)
                 roundCacheKey = undefined;
             history = recovered.history;
-            collectStats(stats, final.stats);
+            collectStats(stats, final.stats, final.stopReason);
             hlog('round stats', { round, wallMs: Date.now() - roundStarted, ...(final.stats ?? {}) });
             const markup = stripToolResponseBlocks(truncateAtControlToken(final.raw.fullText) || recovered.unproven || '');
             let toolCalls = final.toolCalls?.length
@@ -880,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 = [
@@ -891,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),
@@ -912,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);
@@ -926,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.`
@@ -974,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' &&
@@ -1032,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';
@@ -1060,9 +1180,12 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
             tools: undefined,
             generationParams,
             cacheKey: roundCacheKey,
-            signal
+            signal,
+            round: roundsSent,
+            promptPrefix: promptPrefixHash({ system: systemContent, tools: undefined }),
+            capture: captureInferenceCalls
         });
-        collectStats(stats, recovered.final.stats);
+        collectStats(stats, recovered.final.stats, recovered.final.stopReason);
         const answer = recovered.replay ? stripToolCallMarkup(recovered.replay) : '';
         if (answer)
             yield { type: 'content', text: answer };

package/dist-lib/lib/connect.js

@@ -112,6 +112,7 @@ export class RemoteHarness extends EventEmitter {
                 thinkingDefault: context.thinkingDefault,
                 generationParams: context.generationParams,
                 responseFormat: context.responseFormat,
+                captureInferenceCalls: context.captureInferenceCalls,
                 messages: context.messages.map(({ role, content, attachments }) => ({
                     role,
                     content,
@@ -655,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;
@@ -48,6 +49,7 @@ export interface CompletionContext {
     toolConfigs?: Record<string, Record<string, unknown>>;
     generationParams?: LlmGenerationParams;
     responseFormat?: ResponseFormat;
+    captureInferenceCalls?: boolean;
     grantedDirs?: string[];
     grantedDrives?: GrantedDrive[];
     driveOp?: DriveOpFn;

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>;