@botbotgo/agent-harness 0.0.147 → 0.0.149

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.146";
+export declare const AGENT_HARNESS_VERSION = "0.0.148";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.146";
+export const AGENT_HARNESS_VERSION = "0.0.148";

package/dist/runtime/adapter/tool/tool-hitl.d.ts

@@ -1,6 +1,7 @@
 import type { CompiledTool } from "../../../contracts/types.js";
 import type { CompiledAgentBinding } from "../../../contracts/types.js";
 type InterruptFn = <I = unknown, R = unknown>(value: I) => R;
+export declare function toolRequiresRuntimeApproval(compiledTool: CompiledTool): boolean;
 export declare function wrapToolForHumanInTheLoop<T>(resolvedTool: T, compiledTool: CompiledTool, interruptFn?: InterruptFn): T;
 export declare function wrapToolForExecution<T>(resolvedTool: T, compiledTool: CompiledTool, binding?: CompiledAgentBinding, interruptFn?: InterruptFn): T;
 export {};

package/dist/runtime/adapter/tool/tool-hitl.js

@@ -3,6 +3,83 @@ import path from "node:path";
 const DEDUPED_REMOTE_TOOL_NAMES = new Set(["builtin.fetch_url", "builtin.web_search"]);
 const PATH_LIKE_INPUT_KEYS = new Set(["path", "root", "dir", "directory", "cwd"]);
 const ROOT_SCOPING_INPUT_KEYS = new Set(["root", "dir", "directory", "cwd"]);
+const SENSITIVE_MEMORY_LEVELS = new Set(["high", "sensitive", "restricted", "secret", "confidential"]);
+const NON_THREAD_MEMORY_SCOPES = new Set(["workspace", "agent", "user", "project"]);
+const WRITE_LIKE_REMOTE_TOOL_PATTERN = /\b(write|edit|delete|create|update|append|insert|push|commit|publish|send|post|apply|merge|sync|upload|save)\b/i;
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function asString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function readApprovalOverride(compiledTool) {
+    if (compiledTool.config?.requireApproval === true) {
+        return true;
+    }
+    const approval = asRecord(compiledTool.config?.approval);
+    if (approval?.required === true || approval?.enabled === true) {
+        return true;
+    }
+    const mcpConfig = asRecord(compiledTool.config?.mcp);
+    return mcpConfig?.requireApproval === true || mcpConfig?.approvalRequired === true;
+}
+function requiresApprovalForSensitiveMemoryWrite(compiledTool) {
+    const memoryConfig = asRecord(compiledTool.config?.memory);
+    if (memoryConfig?.enabled !== true) {
+        return false;
+    }
+    if (memoryConfig.requireApproval === true || memoryConfig.approvalRequired === true) {
+        return true;
+    }
+    const scope = asString(memoryConfig.scope)?.toLowerCase() ?? "thread";
+    const sensitivity = asString(memoryConfig.sensitivity)?.toLowerCase();
+    if (sensitivity && SENSITIVE_MEMORY_LEVELS.has(sensitivity)) {
+        return true;
+    }
+    return NON_THREAD_MEMORY_SCOPES.has(scope) && sensitivity !== "public" && sensitivity !== "low";
+}
+function requiresApprovalForHighRiskMcpWrite(compiledTool) {
+    if (compiledTool.type !== "mcp") {
+        return false;
+    }
+    if (readApprovalOverride(compiledTool)) {
+        return true;
+    }
+    const mcpConfig = asRecord(compiledTool.config?.mcp);
+    const targetText = [
+        compiledTool.name,
+        compiledTool.description,
+        asString(mcpConfig?.tool),
+        asString(mcpConfig?.ref),
+        asString(mcpConfig?.operation),
+    ]
+        .filter((value) => Boolean(value))
+        .join(" ");
+    return WRITE_LIKE_REMOTE_TOOL_PATTERN.test(targetText);
+}
+export function toolRequiresRuntimeApproval(compiledTool) {
+    if (compiledTool.hitl?.enabled === true) {
+        return true;
+    }
+    return readApprovalOverride(compiledTool) || requiresApprovalForSensitiveMemoryWrite(compiledTool) || requiresApprovalForHighRiskMcpWrite(compiledTool);
+}
+function toolApprovalReason(compiledTool) {
+    if (compiledTool.hitl?.enabled === true) {
+        return undefined;
+    }
+    if (requiresApprovalForSensitiveMemoryWrite(compiledTool)) {
+        return "sensitive-memory-write";
+    }
+    if (requiresApprovalForHighRiskMcpWrite(compiledTool)) {
+        return "high-risk-mcp-write";
+    }
+    if (readApprovalOverride(compiledTool)) {
+        return "runtime-policy";
+    }
+    return undefined;
+}
 function toInputPreview(input) {
     if (typeof input === "object" && input && !Array.isArray(input)) {
         return input;
@@ -25,7 +102,7 @@ function resolveApprovedInput(originalInput, resumeValue) {
     return originalInput;
 }
 export function wrapToolForHumanInTheLoop(resolvedTool, compiledTool, interruptFn = interrupt) {
-    if (!compiledTool.hitl?.enabled || typeof resolvedTool !== "object" || resolvedTool === null) {
+    if (!toolRequiresRuntimeApproval(compiledTool) || typeof resolvedTool !== "object" || resolvedTool === null) {
         return resolvedTool;
     }
     const target = resolvedTool;
@@ -35,6 +112,7 @@ export function wrapToolForHumanInTheLoop(resolvedTool, compiledTool, interruptF
             toolId: compiledTool.id,
             allowedDecisions: compiledTool.hitl?.allow ?? ["approve", "edit", "reject"],
             inputPreview: toInputPreview(input),
+            ...(toolApprovalReason(compiledTool) ? { approvalReason: toolApprovalReason(compiledTool) } : {}),
         });
         const approvedInput = resolveApprovedInput(input, resumed);
         if (approvedInput === Symbol.for("agent-harness.hitl.reject")) {

package/dist/runtime/harness/bindings.js

@@ -1,4 +1,5 @@
 import { resolveBindingTimeout, resolveProviderRetryPolicy, resolveStreamIdleTimeout } from "../adapter/resilience.js";
+import { toolRequiresRuntimeApproval } from "../adapter/tool/tool-hitl.js";
 import { getBindingPrimaryTools } from "../support/compiled-binding.js";
 export function getWorkspaceBinding(workspace, agentId) {
     return workspace.bindings.get(agentId);
@@ -29,7 +30,7 @@ export function projectBindingToolExecutionPolicy(binding) {
         name: tool.name,
         retryable: tool.retryable === true,
         hasInputSchema: typeof tool.inputSchemaRef === "string" && tool.inputSchemaRef.trim().length > 0,
-        requiresApproval: tool.hitl?.enabled === true,
+        requiresApproval: toolRequiresRuntimeApproval(tool),
     }));
     const retryableToolCount = projectedTools.filter((tool) => tool.retryable).length;
     return {

package/dist/runtime/harness/events/events.js

@@ -59,8 +59,16 @@ export async function requestApprovalAndEmitEvent(runtime, threadId, runId, inpu
     return { approval, event };
 }
 export async function emitSyntheticFallbackEvent(runtime, threadId, runId, selectedAgentId, error, sequence = 3) {
+    const payload = typeof error === "object" && error !== null && "reason" in error
+        ? {
+            ...error,
+            selectedAgentId,
+        }
+        : {
+            reason: error instanceof Error ? error.message : String(error),
+            selectedAgentId,
+        };
     await emitHarnessEvent(runtime, threadId, runId, sequence, "runtime.synthetic_fallback", {
-        reason: error instanceof Error ? error.message : String(error),
-        selectedAgentId,
+        ...payload,
     });
 }

package/dist/runtime/harness/run/stream-run.js

@@ -46,6 +46,7 @@ export async function* streamHarnessRun(options) {
     let nonUpstreamStreamActivityObserved = false;
     let currentAgentId = options.selectedAgentId;
     let delegationChain = [options.selectedAgentId];
+    let syntheticFallback;
     try {
         const [priorHistory, acquiredReleaseRunSlot] = await Promise.all([
             priorHistoryPromise,
@@ -237,6 +238,13 @@ export async function* streamHarnessRun(options) {
             return;
         }
         try {
+            syntheticFallback = {
+                strategy: "stream-to-invoke",
+                sourceStage: "stream",
+                reason: error instanceof Error ? error.message : String(error),
+                outcome: "recovered",
+            };
+            await options.emitSyntheticFallback(options.threadId, options.runId, options.selectedAgentId, syntheticFallback);
             const actual = await options.invokeWithHistory(options.binding, options.input, options.threadId, options.runId);
             await options.appendAssistantMessage(options.threadId, options.runId, actual.output);
             if (Array.isArray(actual.contentBlocks) && actual.contentBlocks.length > 0) {
@@ -249,6 +257,10 @@ export async function* streamHarnessRun(options) {
                     threadId: options.threadId,
                     runId: options.runId,
                     agentId: currentAgentId,
+                    metadata: {
+                        ...(actual.metadata ?? {}),
+                        syntheticFallback,
+                    },
                 },
             };
             yield {
@@ -260,7 +272,13 @@ export async function* streamHarnessRun(options) {
             return;
         }
         catch (invokeError) {
-            await options.emitSyntheticFallback(options.threadId, options.runId, options.selectedAgentId, invokeError);
+            syntheticFallback = {
+                strategy: "stream-to-invoke",
+                sourceStage: "stream",
+                reason: invokeError instanceof Error ? invokeError.message : String(invokeError),
+                outcome: "failed",
+            };
+            await options.emitSyntheticFallback(options.threadId, options.runId, options.selectedAgentId, syntheticFallback);
             const runtimeFailure = renderRuntimeFailure(invokeError);
             yield {
                 type: "event",
@@ -285,6 +303,9 @@ export async function* streamHarnessRun(options) {
                     state: "failed",
                     output: runtimeFailure,
                     finalMessageText: runtimeFailure,
+                    metadata: {
+                        syntheticFallback,
+                    },
                 },
             };
             return;

package/dist/tool-modules.d.ts

@@ -10,6 +10,8 @@ export type LoadedToolModule = {
         enabled: boolean;
         kind?: string;
         scope?: string;
+        sensitivity?: string;
+        requireApproval?: boolean;
         maxCandidates?: number;
         tags?: string[];
     };

package/dist/tools.d.ts

@@ -10,6 +10,8 @@ export type ToolDefinitionObject = {
         enabled: boolean;
         kind?: string;
         scope?: string;
+        sensitivity?: string;
+        requireApproval?: boolean;
         maxCandidates?: number;
         tags?: string[];
     };
@@ -28,6 +30,8 @@ export declare function tool(definition: {
         enabled: boolean;
         kind?: string;
         scope?: string;
+        sensitivity?: string;
+        requireApproval?: boolean;
         maxCandidates?: number;
         tags?: string[];
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.147",
+  "version": "0.0.149",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",