@botbotgo/agent-harness 0.0.145 → 0.0.147

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/contracts/runtime.d.ts

@@ -90,12 +90,19 @@ export type RuntimeSnapshotSkill = {
     path: string;
     description?: string;
 };
+export type RuntimeSnapshotTracing = {
+    enabled: boolean;
+    correlationId: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+};
 export type RuntimeSnapshot = {
     agentId: string;
     model?: RuntimeSnapshotModel;
     tools: RuntimeSnapshotTool[];
     skills: RuntimeSnapshotSkill[];
     memory: string[];
+    tracing?: RuntimeSnapshotTracing;
 };
 export type MemoryCandidate = {
     content: string;

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.144";
+export declare const AGENT_HARNESS_VERSION = "0.0.146";

package/dist/package-version.js

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

package/dist/runtime/harness/run/inspection.d.ts

@@ -1,5 +1,7 @@
 import type { CompiledAgentBinding, RuntimeSnapshot } from "../../../contracts/types.js";
-export declare function buildRunRuntimeSnapshot(binding: CompiledAgentBinding): RuntimeSnapshot;
+export declare function buildRunRuntimeSnapshot(binding: CompiledAgentBinding, options?: {
+    runId?: string;
+}): RuntimeSnapshot;
 export declare function consumeRunInspectionUpstreamEvent(input: {
     event: unknown;
     currentAgentId: string;

package/dist/runtime/harness/run/inspection.js

@@ -6,8 +6,38 @@ function asObject(value) {
 function readStringArray(value) {
     return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim().length > 0) : [];
 }
-export function buildRunRuntimeSnapshot(binding) {
+function readTracingConfig(binding) {
+    const deepAgentTracing = asObject(binding.harnessRuntime?.deepagent?.passthrough)?.tracing;
+    const langchainTracing = asObject(binding.harnessRuntime?.langchain?.passthrough)?.tracing;
+    const legacyDeepAgentTracing = asObject(binding.deepAgentParams?.passthrough)?.tracing;
+    const legacyLangChainTracing = asObject(binding.langchainAgentParams?.passthrough)?.tracing;
+    return (asObject(langchainTracing) ??
+        asObject(deepAgentTracing) ??
+        asObject(legacyLangChainTracing) ??
+        asObject(legacyDeepAgentTracing) ??
+        null);
+}
+function buildRuntimeSnapshotTracing(binding, runId) {
+    const tracing = readTracingConfig(binding);
+    if (!tracing) {
+        return undefined;
+    }
+    const enabled = tracing.enabled !== false;
+    if (!enabled || !runId) {
+        return undefined;
+    }
+    const tags = readStringArray(tracing.tags);
+    const metadata = asObject(tracing.metadata);
+    return {
+        enabled: true,
+        correlationId: runId,
+        ...(tags.length > 0 ? { tags } : {}),
+        ...(metadata && Object.keys(metadata).length > 0 ? { metadata: { ...metadata } } : {}),
+    };
+}
+export function buildRunRuntimeSnapshot(binding, options) {
     const model = getBindingPrimaryModel(binding);
+    const tracing = buildRuntimeSnapshotTracing(binding, options?.runId);
     const init = typeof model?.init === "object" && model.init ? model.init : {};
     const baseUrl = typeof init.baseUrl === "string" && init.baseUrl.trim().length > 0
         ? init.baseUrl.trim()
@@ -37,6 +67,7 @@ export function buildRunRuntimeSnapshot(binding) {
             };
         }),
         memory: getBindingMemorySources(binding),
+        ...(tracing ? { tracing } : {}),
     };
 }
 function maybeAppendAgent(chain, agentId) {

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

@@ -14,7 +14,7 @@ export async function ensureThreadStarted(runtime, input) {
     const startedAt = createdAt;
     const currentAgentId = selectedAgentId;
     const delegationChain = [selectedAgentId];
-    const runtimeSnapshot = buildRunRuntimeSnapshot(binding);
+    const runtimeSnapshot = buildRunRuntimeSnapshot(binding, { runId });
     const userMessage = {
         role: "user",
         content: normalizeMessageContent(message),

package/package.json

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