@botbotgo/agent-harness 0.0.146 → 0.0.148

package/README.md

@@ -346,7 +346,33 @@ Use `invocation` as the runtime-facing request envelope:
 
 - `invocation.context` for request-scoped execution context
 - `invocation.inputs` for structured runtime inputs
-- `invocation.attachments` for attachment-like payloads that the active backend can interpret
+- `invocation.attachments` for auxiliary invocation-scoped attachment payloads that the active backend can interpret
+
+For multimodal chat turns, keep the user-visible content in `input`.
+
+- if the product would show the image or text in the chat transcript, it belongs in `input`
+- if the payload is auxiliary run-scoped data rather than the chat turn itself, it belongs in `invocation.attachments`
+- persistence, replay, and transcript inspection should treat `input` as the source of truth for user-visible multimodal chat content
+
+```ts
+import { normalizeUserChatInput, run } from "@botbotgo/agent-harness";
+
+const result = await run(
+  runtime,
+  {
+    agentId: "orchestra",
+    ...normalizeUserChatInput({
+      role: "user",
+      content: [
+        { type: "text", text: "Describe the image and call out any risks." },
+        { type: "image_url", image_url: "data:image/png;base64,..." },
+      ],
+    }),
+  },
+);
+```
+
+Use `normalizeUserChatInput(...)` when a product already has chat-style user messages and wants to project one user turn onto the stable `run(..., { input, invocation })` surface without introducing a separate harness-owned chat API.
 
 ### Let The Runtime Route
 

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { CancelOptions, RequestRecord, RequestSummary, ResumeOptions, RunDecisionOptions, RunResult, RunStartOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, SessionRecord, SessionSummary, WorkspaceLoadOptions } from "./contracts/types.js";
+import type { CancelOptions, InvocationEnvelope, MessageContent, RequestRecord, RequestSummary, ResumeOptions, RunDecisionOptions, RunResult, RunStartOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, SessionRecord, SessionSummary, WorkspaceLoadOptions } from "./contracts/types.js";
 import { AgentHarnessRuntime } from "./runtime/harness.js";
 import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/harness/system/inventory.js";
 import type { RequirementAssessmentOptions } from "./runtime/harness/system/skill-requirements.js";
@@ -34,6 +34,14 @@ type PublicRunResult = Omit<RunResult, "threadId" | "runId"> & {
     sessionId: string;
     requestId: string;
 };
+export type UserChatMessage = {
+    role: "user";
+    content: MessageContent;
+};
+export type UserChatInput = MessageContent | UserChatMessage;
+export type NormalizeUserChatInputOptions = {
+    invocation?: InvocationEnvelope;
+};
 type CreateAgentHarnessOptions = {
     /**
      * Workspace loading behavior.
@@ -44,6 +52,7 @@ type CreateAgentHarnessOptions = {
 };
 export declare function createAgentHarness(): Promise<AgentHarnessRuntime>;
 export declare function createAgentHarness(workspaceRoot: string, options?: CreateAgentHarnessOptions): Promise<AgentHarnessRuntime>;
+export declare function normalizeUserChatInput(input: UserChatInput, options?: NormalizeUserChatInputOptions): Pick<RunStartOptions, "input" | "invocation">;
 export declare function run(runtime: AgentHarnessRuntime, options: PublicRunOptions): Promise<PublicRunResult>;
 export declare function subscribe(runtime: AgentHarnessRuntime, listener: Parameters<AgentHarnessRuntime["subscribe"]>[0]): () => void;
 export declare function listSessions(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listThreads"]>[0]): Promise<SessionSummary[]>;

package/dist/api.js

@@ -1,4 +1,5 @@
 import { AgentHarnessRuntime } from "./runtime/harness.js";
+import { normalizeMessageContent } from "./utils/message-content.js";
 import { loadWorkspace } from "./workspace/compile.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
 export { createUpstreamTimelineReducer } from "./upstream-events.js";
@@ -118,6 +119,12 @@ export async function createAgentHarness(workspaceRoot = process.cwd(), options
     await harness.initialize();
     return harness;
 }
+export function normalizeUserChatInput(input, options = {}) {
+    const content = typeof input === "object" && input !== null && "role" in input
+        ? normalizeUserChatMessage(input).content
+        : normalizeMessageContent(input);
+    return options.invocation ? { input: content, invocation: options.invocation } : { input: content };
+}
 export async function run(runtime, options) {
     return toPublicRunResult(await runtime.run(toInternalRunOptions(options)));
 }
@@ -186,3 +193,12 @@ export async function createToolMcpServer(runtime, options) {
 export async function serveToolsOverStdio(runtime, options) {
     return runtime.serveToolsOverStdio(options);
 }
+function normalizeUserChatMessage(message) {
+    if (message.role !== "user") {
+        throw new Error("normalizeUserChatInput only accepts user-role chat messages.");
+    }
+    return {
+        role: "user",
+        content: normalizeMessageContent(message.content),
+    };
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, normalizeUserChatInput, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export type { NormalizeUserChatInputOptions, UserChatInput, UserChatMessage } from "./api.js";
 export type { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";
 export type { UpstreamTimelineProjection, UpstreamTimelineReducer } from "./upstream-events.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, normalizeUserChatInput, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.145";
+export declare const AGENT_HARNESS_VERSION = "0.0.147";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.145";
+export const AGENT_HARNESS_VERSION = "0.0.147";

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/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.146",
+  "version": "0.0.148",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",