@botbotgo/agent-harness 0.0.164 → 0.0.166

package/README.md

@@ -28,7 +28,7 @@
 
 <p align="center">
   <a href="https://botbotgo.github.io/agent-harness/development/">Developer docs</a>
-  (multi-page static docs in <code>docs/development/</code>)
+  (<code>docs/development/</code>, English / 中文)
 </p>
 
 <p align="center">
@@ -902,6 +902,7 @@ Primary exports:
 - `createAcpServer`
 - `serveAcpHttp`
 - `serveAcpStdio`
+- `serveAgUiHttp`
 - `createToolMcpServer`
 - `serveToolsOverStdio`
 - `stop`
@@ -923,5 +924,6 @@ ACP transport notes:
 
 - `serveAcpStdio(runtime)` exposes newline-delimited JSON-RPC over stdio for local IDE, CLI, or subprocess clients.
 - `serveAcpHttp(runtime)` exposes JSON-RPC over HTTP plus SSE runtime events so remote operator surfaces can connect without importing the runtime in-process.
+- `serveAgUiHttp(runtime)` exposes a minimal AG-UI-compatible HTTP SSE bridge that projects `run + output.delta + final result` onto `RUN_STARTED`, `TEXT_MESSAGE_*`, and `RUN_FINISHED` events for UI clients.
 - `exportRunPackage(...)` and `exportSessionPackage(...)` package stable runtime records, transcript, approvals, events, and artifacts for operator tooling without reaching into persistence internals.
 - `runtime/default.governance.remoteMcp` can now deny or allow specific MCP servers, raise approval requirements by transport, and stamp transport-based risk tiers into runtime governance bundles.

package/README.zh.md

@@ -28,7 +28,7 @@
 
 <p align="center">
   <a href="https://botbotgo.github.io/agent-harness/development/">开发文档</a>
-  （多页面静态文档位于 <code>docs/development/</code>）
+  （多页面静态文档位于 <code>docs/development/</code>，支持 English / 中文）
 </p>
 
 <p align="center">
@@ -861,6 +861,7 @@ spec:
 - `createAcpServer`
 - `serveAcpHttp`
 - `serveAcpStdio`
+- `serveAgUiHttp`
 - `createToolMcpServer`
 - `serveToolsOverStdio`
 - `stop`
@@ -882,5 +883,6 @@ ACP transport 说明：
 
 - `serveAcpStdio(runtime)` 提供基于 stdio 的 newline-delimited JSON-RPC，适合本地 IDE、CLI 或子进程客户端。
 - `serveAcpHttp(runtime)` 提供基于 HTTP 的 JSON-RPC 与 SSE runtime events，适合远程 operator surface 或独立控制面接入。
+- `serveAgUiHttp(runtime)` 提供最小可用的 AG-UI HTTP SSE bridge，把现有 `run + output.delta + final result` 投影成 `RUN_STARTED`、`TEXT_MESSAGE_*` 与 `RUN_FINISHED` 事件，便于 UI 客户端直接接入。
 - `exportRunPackage(...)` 与 `exportSessionPackage(...)` 可把稳定 runtime 记录、transcript、approvals、events 和 artifacts 打包给 operator tooling，而不必直接访问 persistence 内部实现。
 - `runtime/default.governance.remoteMcp` 现在可以按 MCP server 或 transport 做 allow/deny、审批升级，并把 transport 风险等级写进 runtime governance bundles。

package/dist/api.d.ts

@@ -11,6 +11,7 @@ export { createUpstreamTimelineReducer } from "./upstream-events.js";
 export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, RuntimeRunPackage, RuntimeRunPackageInput, RuntimeSessionPackage, RuntimeSessionPackageInput, UpdateMemoryInput, } from "./contracts/types.js";
 export type { AcpHttpServer, AcpHttpServerOptions } from "./protocol/acp/http.js";
 export type { AcpStdioServer, AcpStdioServerOptions } from "./protocol/acp/stdio.js";
+export type { AgUiEvent, AgUiHttpServer, AgUiHttpServerOptions, AgUiRunAgentInput } from "./protocol/ag-ui/http.js";
 type PublicApprovalRecord = {
     approvalId: string;
     pendingActionId: string;
@@ -97,6 +98,7 @@ export declare function exportEvaluationBundle(runtime: AgentHarnessRuntime, inp
 export declare function replayEvaluationBundle(runtime: AgentHarnessRuntime, input: RuntimeEvaluationReplayInput): Promise<RuntimeEvaluationReplayResult>;
 export declare function serveAcpStdio(runtime: AgentHarnessRuntime, options?: import("./protocol/acp/stdio.js").AcpStdioServerOptions): import("./protocol/acp/stdio.js").AcpStdioServer;
 export declare function serveAcpHttp(runtime: AgentHarnessRuntime, options?: import("./protocol/acp/http.js").AcpHttpServerOptions): Promise<import("./protocol/acp/http.js").AcpHttpServer>;
+export declare function serveAgUiHttp(runtime: AgentHarnessRuntime, options?: import("./protocol/ag-ui/http.js").AgUiHttpServerOptions): Promise<import("./protocol/ag-ui/http.js").AgUiHttpServer>;
 export declare function listAgentSkills(runtime: AgentHarnessRuntime, agentId: string, options?: RequirementAssessmentOptions): InventorySkillRecord[];
 export declare function getAgent(runtime: AgentHarnessRuntime, agentId: string, options?: RequirementAssessmentOptions): InventoryAgentRecord | null;
 export declare function describeInventory(runtime: AgentHarnessRuntime, options?: RequirementAssessmentOptions): {

package/dist/api.js

@@ -1,4 +1,5 @@
 import { AgentHarnessRuntime } from "./runtime/harness.js";
+import { serveAgUiOverHttp } from "./protocol/ag-ui/http.js";
 import { serveAcpOverHttp } from "./protocol/acp/http.js";
 import { serveAcpOverStdio } from "./protocol/acp/stdio.js";
 import { normalizeMessageContent } from "./utils/message-content.js";
@@ -212,6 +213,9 @@ export function serveAcpStdio(runtime, options) {
 export async function serveAcpHttp(runtime, options) {
     return serveAcpOverHttp(runtime, options);
 }
+export async function serveAgUiHttp(runtime, options) {
+    return serveAgUiOverHttp(runtime, options);
+}
 export function listAgentSkills(runtime, agentId, options) {
     return runtime.listAgentSkills(agentId, options);
 }

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { createAgentHarness } from "./api.js";
+import { serveAgUiOverHttp } from "./protocol/ag-ui/http.js";
 import { serveAcpOverHttp } from "./protocol/acp/http.js";
 import { serveAcpOverStdio } from "./protocol/acp/stdio.js";
 type CliIo = {
@@ -9,6 +10,7 @@ type CliIo = {
 };
 type CliDeps = {
     createAgentHarness?: typeof createAgentHarness;
+    serveAgUiOverHttp?: typeof serveAgUiOverHttp;
     serveAcpOverHttp?: typeof serveAcpOverHttp;
     serveAcpOverStdio?: typeof serveAcpOverStdio;
 };

package/dist/cli.js

@@ -3,12 +3,14 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { createAgentHarness } from "./api.js";
 import { initProject } from "./init-project.js";
+import { serveAgUiOverHttp } from "./protocol/ag-ui/http.js";
 import { serveAcpOverHttp } from "./protocol/acp/http.js";
 import { serveAcpOverStdio } from "./protocol/acp/stdio.js";
 function renderUsage() {
     return `Usage:
   agent-harness init <project-name> [--template deep-research|single-agent] [--provider <provider>] [--model <model>] [--with-web-search|--no-web-search]
   agent-harness acp serve [--workspace <path>] [--transport stdio|http] [--host <hostname>] [--port <port>]
+  agent-harness ag-ui serve [--workspace <path>] [--host <hostname>] [--port <port>]
 `;
 }
 function isTemplate(value) {
@@ -104,12 +106,54 @@ function parseAcpServeOptions(args) {
     }
     return { workspaceRoot, transport, hostname, port };
 }
+function parseHttpServeOptions(args) {
+    let workspaceRoot;
+    let hostname;
+    let port;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--workspace") {
+            const value = args[index + 1];
+            if (!value) {
+                return { hostname, port, error: "Missing value for --workspace" };
+            }
+            workspaceRoot = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--host") {
+            const value = args[index + 1];
+            if (!value) {
+                return { workspaceRoot, port, error: "Missing value for --host" };
+            }
+            hostname = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--port") {
+            const value = args[index + 1];
+            if (!value) {
+                return { workspaceRoot, hostname, error: "Missing value for --port" };
+            }
+            const parsedPort = Number.parseInt(value, 10);
+            if (!Number.isFinite(parsedPort) || parsedPort < 0) {
+                return { workspaceRoot, hostname, error: `Invalid AG-UI port: ${value}` };
+            }
+            port = parsedPort;
+            index += 1;
+            continue;
+        }
+        return { workspaceRoot, hostname, port, error: `Unknown option: ${arg}` };
+    }
+    return { workspaceRoot, hostname, port };
+}
 export async function runCli(argv, io = {}, deps = {}) {
     const cwd = io.cwd ?? process.cwd();
     const stdout = io.stdout ?? ((message) => process.stdout.write(message));
     const stderr = io.stderr ?? ((message) => process.stderr.write(message));
     const [command, projectName, ...rest] = argv;
     const createHarness = deps.createAgentHarness ?? createAgentHarness;
+    const serveAgUi = deps.serveAgUiOverHttp ?? serveAgUiOverHttp;
     const serveAcpHttp = deps.serveAcpOverHttp ?? serveAcpOverHttp;
     const serveAcp = deps.serveAcpOverStdio ?? serveAcpOverStdio;
     if (command === "init") {
@@ -179,6 +223,36 @@ export async function runCli(argv, io = {}, deps = {}) {
             return 1;
         }
     }
+    if (command === "ag-ui") {
+        const [subcommand, ...subcommandArgs] = [projectName, ...rest];
+        if (subcommand !== "serve") {
+            stderr(renderUsage());
+            return 1;
+        }
+        const parsed = parseHttpServeOptions(subcommandArgs);
+        if (parsed.error) {
+            stderr(`${parsed.error}\n`);
+            stderr(renderUsage());
+            return 1;
+        }
+        try {
+            const runtime = await createHarness(path.resolve(cwd, parsed.workspaceRoot ?? "."));
+            const workspacePath = path.resolve(cwd, parsed.workspaceRoot ?? ".");
+            const server = await serveAgUi(runtime, {
+                hostname: parsed.hostname,
+                port: parsed.port,
+            });
+            stderr(`Serving AG-UI over http from ${workspacePath} at ${server.runUrl}\n`);
+            await server.completed;
+            await runtime.stop();
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            stderr(`${message}\n`);
+            return 1;
+        }
+    }
     stderr(renderUsage());
     return 1;
 }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRunPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, listRunEvents, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveAcpHttp, serveAcpStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRunPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, listRunEvents, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
 export type { AcpApproval, AcpArtifact, AcpEventNotification, AcpJsonRpcError, AcpJsonRpcRequest, AcpJsonRpcResponse, AcpJsonRpcSuccess, AcpRequestRecord, AcpRunRequestParams, AcpServerCapabilities, AcpSessionRecord, } from "./acp.js";
 export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, RuntimeRunPackage, RuntimeRunPackageInput, RuntimeSessionPackage, RuntimeSessionPackageInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
 export type { BuildFlowGraphInput, FlowEdge, FlowEdgeKind, FlowGraph, FlowGraphMermaidOptions, FlowGraphSequenceMermaidOptions, FlowGroup, FlowGroupKind, FlowNode, FlowNodeKind, FlowNodeLayer, FlowNodeStatus, } from "./flow/index.js";
-export type { AcpHttpServer, AcpHttpServerOptions, AcpStdioServer, AcpStdioServerOptions } from "./api.js";
+export type { AcpHttpServer, AcpHttpServerOptions, AcpStdioServer, AcpStdioServerOptions, AgUiEvent, AgUiHttpServer, AgUiHttpServerOptions, AgUiRunAgentInput, } 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 { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRunPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, listRunEvents, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveAcpHttp, serveAcpStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRunPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, listRunEvents, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.163";
+export declare const AGENT_HARNESS_VERSION = "0.0.165";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.163";
+export const AGENT_HARNESS_VERSION = "0.0.165";

package/dist/protocol/ag-ui/http.d.ts

@@ -0,0 +1,56 @@
+import type { AgentHarnessRuntime } from "../../runtime/harness.js";
+import type { MessageContent } from "../../contracts/types.js";
+export type AgUiHttpServerOptions = {
+    hostname?: string;
+    port?: number;
+    runPath?: string;
+};
+export type AgUiRunAgentInput = {
+    input: MessageContent;
+    agentId?: string;
+    sessionId?: string;
+    invocation?: Record<string, unknown>;
+};
+type AgUiBaseEvent = {
+    type: string;
+    timestamp: string;
+};
+export type AgUiEvent = (AgUiBaseEvent & {
+    type: "RUN_STARTED";
+    threadId: string;
+    runId: string;
+    input?: MessageContent;
+}) | (AgUiBaseEvent & {
+    type: "TEXT_MESSAGE_START";
+    messageId: string;
+    role: "assistant";
+}) | (AgUiBaseEvent & {
+    type: "TEXT_MESSAGE_CONTENT";
+    messageId: string;
+    delta: string;
+}) | (AgUiBaseEvent & {
+    type: "TEXT_MESSAGE_END";
+    messageId: string;
+}) | (AgUiBaseEvent & {
+    type: "RUN_FINISHED";
+    threadId: string;
+    runId: string;
+    state?: string;
+    approvalId?: string;
+    pendingActionId?: string;
+}) | (AgUiBaseEvent & {
+    type: "RUN_ERROR";
+    message: string;
+    runId?: string;
+    threadId?: string;
+});
+export type AgUiHttpServer = {
+    hostname: string;
+    port: number;
+    runPath: string;
+    runUrl: string;
+    completed: Promise<void>;
+    close: () => Promise<void>;
+};
+export declare function serveAgUiOverHttp(runtime: AgentHarnessRuntime, options?: AgUiHttpServerOptions): Promise<AgUiHttpServer>;
+export {};

package/dist/protocol/ag-ui/http.js

@@ -0,0 +1,194 @@
+import { createServer } from "node:http";
+import { createPersistentId } from "../../utils/id.js";
+function normalizePath(value, fallback) {
+    const source = typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+    return source.startsWith("/") ? source : `/${source}`;
+}
+function readRequestBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        request.on("data", (chunk) => {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        request.on("error", reject);
+    });
+}
+function writeSseEvent(response, payload) {
+    return new Promise((resolve, reject) => {
+        response.write(`data: ${JSON.stringify(payload)}\n\n`, (error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}
+function parseRunInput(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        throw new Error("AG-UI run input must be an object.");
+    }
+    const typed = payload;
+    if (typeof typed.input !== "string"
+        && !(Array.isArray(typed.input))) {
+        throw new Error("AG-UI run input requires `input`.");
+    }
+    return {
+        input: typed.input,
+        ...(typeof typed.agentId === "string" && typed.agentId.trim().length > 0 ? { agentId: typed.agentId.trim() } : {}),
+        ...(typeof typed.sessionId === "string" && typed.sessionId.trim().length > 0 ? { sessionId: typed.sessionId.trim() } : {}),
+        ...(typed.invocation && typeof typed.invocation === "object" && !Array.isArray(typed.invocation)
+            ? { invocation: typed.invocation }
+            : {}),
+    };
+}
+function createTimestamp() {
+    return new Date().toISOString();
+}
+function toRunStarted(event, input) {
+    return {
+        type: "RUN_STARTED",
+        timestamp: createTimestamp(),
+        threadId: event.threadId,
+        runId: event.runId,
+        input,
+    };
+}
+export async function serveAgUiOverHttp(runtime, options = {}) {
+    const hostname = options.hostname?.trim() || "127.0.0.1";
+    const port = typeof options.port === "number" && Number.isFinite(options.port) ? options.port : 0;
+    const runPath = normalizePath(options.runPath, "/run");
+    const httpServer = createServer(async (request, response) => {
+        const url = new URL(request.url ?? "/", `http://${hostname}`);
+        if (request.method !== "POST" || url.pathname !== runPath) {
+            response.statusCode = 404;
+            response.setHeader("content-type", "application/json; charset=utf-8");
+            response.end(JSON.stringify({ error: "Not Found", runPath }));
+            return;
+        }
+        response.statusCode = 200;
+        response.setHeader("content-type", "text/event-stream; charset=utf-8");
+        response.setHeader("cache-control", "no-cache, no-transform");
+        response.setHeader("connection", "keep-alive");
+        let runId;
+        let threadId;
+        let messageId;
+        let textMessageStarted = false;
+        const ensureTextStart = async () => {
+            if (textMessageStarted) {
+                return;
+            }
+            messageId = messageId ?? `msg-${createPersistentId()}`;
+            textMessageStarted = true;
+            await writeSseEvent(response, {
+                type: "TEXT_MESSAGE_START",
+                timestamp: createTimestamp(),
+                messageId,
+                role: "assistant",
+            });
+        };
+        try {
+            const body = await readRequestBody(request);
+            const input = parseRunInput(JSON.parse(body));
+            const result = await runtime.run({
+                agentId: input.agentId,
+                input: input.input,
+                ...(input.sessionId ? { threadId: input.sessionId } : {}),
+                ...(input.invocation ? { invocation: input.invocation } : {}),
+                listeners: {
+                    onEvent: async (event) => {
+                        if (event.eventType === "run.created") {
+                            runId = event.runId;
+                            threadId = event.threadId;
+                            await writeSseEvent(response, toRunStarted(event, input.input));
+                            return;
+                        }
+                        if (event.eventType === "output.delta") {
+                            runId = runId ?? event.runId;
+                            threadId = threadId ?? event.threadId;
+                            const delta = typeof event.payload.content === "string" ? event.payload.content : "";
+                            if (!delta) {
+                                return;
+                            }
+                            await ensureTextStart();
+                            await writeSseEvent(response, {
+                                type: "TEXT_MESSAGE_CONTENT",
+                                timestamp: createTimestamp(),
+                                messageId: messageId,
+                                delta,
+                            });
+                        }
+                    },
+                },
+            });
+            runId = runId ?? result.runId;
+            threadId = threadId ?? result.threadId;
+            if (!textMessageStarted && result.output) {
+                await ensureTextStart();
+                await writeSseEvent(response, {
+                    type: "TEXT_MESSAGE_CONTENT",
+                    timestamp: createTimestamp(),
+                    messageId: messageId,
+                    delta: result.output,
+                });
+            }
+            if (textMessageStarted) {
+                await writeSseEvent(response, {
+                    type: "TEXT_MESSAGE_END",
+                    timestamp: createTimestamp(),
+                    messageId: messageId,
+                });
+            }
+            await writeSseEvent(response, {
+                type: "RUN_FINISHED",
+                timestamp: createTimestamp(),
+                threadId: threadId,
+                runId: runId,
+                state: result.state,
+                ...(result.approvalId ? { approvalId: result.approvalId } : {}),
+                ...(result.pendingActionId ? { pendingActionId: result.pendingActionId } : {}),
+            });
+        }
+        catch (error) {
+            await writeSseEvent(response, {
+                type: "RUN_ERROR",
+                timestamp: createTimestamp(),
+                ...(threadId ? { threadId } : {}),
+                ...(runId ? { runId } : {}),
+                message: error instanceof Error ? error.message : "AG-UI run failed.",
+            });
+        }
+        finally {
+            response.end();
+        }
+    });
+    const completed = new Promise((resolve, reject) => {
+        httpServer.once("close", resolve);
+        httpServer.once("error", reject);
+    });
+    await new Promise((resolve, reject) => {
+        httpServer.listen(port, hostname, () => resolve());
+        httpServer.once("error", reject);
+    });
+    const address = httpServer.address();
+    const resolvedPort = typeof address === "object" && address ? address.port : port;
+    return {
+        hostname,
+        port: resolvedPort,
+        runPath,
+        runUrl: `http://${hostname}:${resolvedPort}${runPath}`,
+        completed,
+        close: async () => {
+            await new Promise((resolve, reject) => {
+                httpServer.close((error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        },
+    };
+}

package/dist/runtime/adapter/local-tool-invocation.js

@@ -49,7 +49,7 @@ export async function runLocalToolInvocationLoop({ binding, request, primaryTool
                 throw new Error(`Tool ${toolCall.name} is not configured for this agent.`);
             }
             const compiledTool = toolCatalog.get(toolCall.name) ?? toolCatalog.get(resolvedToolName);
-            const normalizedArgs = normalizeToolArgsForSchema(toolCall.args, activeExecutable.schema);
+            const normalizedArgs = normalizeToolArgsForSchema(toolCall.args, activeExecutable.schema, toolCall.rawArgsInput);
             const toolResult = await activeExecutable.invoke(normalizedArgs);
             const memoryCandidates = compiledTool ? extractMemoryCandidatesFromToolOutput(compiledTool, toolResult) : [];
             executedToolResults.push({

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

@@ -1,7 +1,8 @@
 export declare function stringifyToolOutput(output: unknown): string;
-export declare function normalizeToolArgsForSchema(args: Record<string, unknown>, schema: unknown): Record<string, unknown>;
+export declare function normalizeToolArgsForSchema(args: Record<string, unknown>, schema: unknown, rawArgsInput?: unknown): Record<string, unknown>;
 export declare function extractToolCallsFromResult(result: unknown): Array<{
     id?: string;
     name: string;
     args: Record<string, unknown>;
+    rawArgsInput?: unknown;
 }>;

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

@@ -14,7 +14,29 @@ export function stringifyToolOutput(output) {
         return `${String(output)}`;
     }
 }
-export function normalizeToolArgsForSchema(args, schema) {
+function mapSingleFieldScalarArg(args, expectedKey, rawArgsInput) {
+    if (expectedKey in args) {
+        return args;
+    }
+    if (typeof rawArgsInput === "string") {
+        const trimmed = rawArgsInput.trim();
+        if (trimmed.length === 0) {
+            return args;
+        }
+        return {
+            ...args,
+            [expectedKey]: trimmed,
+        };
+    }
+    if (typeof rawArgsInput === "number" || typeof rawArgsInput === "boolean") {
+        return {
+            ...args,
+            [expectedKey]: rawArgsInput,
+        };
+    }
+    return args;
+}
+export function normalizeToolArgsForSchema(args, schema, rawArgsInput) {
     const schemaDef = isObject(schema) ? schema._def : undefined;
     const shape = schemaDef
         ? isRecord(schemaDef.shape)
@@ -34,19 +56,23 @@ export function normalizeToolArgsForSchema(args, schema) {
     if (expectedKey in args) {
         return args;
     }
+    const scalarMappedArgs = mapSingleFieldScalarArg(args, expectedKey, rawArgsInput);
+    if (expectedKey in scalarMappedArgs) {
+        return scalarMappedArgs;
+    }
     const aliasesByExpected = {
         city: ["location", "locality", "place"],
         location: ["city", "city_name"],
         query: ["question", "prompt", "text", "request"],
     };
     const aliases = aliasesByExpected[expectedKey] ?? [];
-    const aliasKey = aliases.find((candidate) => candidate in args);
-    if (!aliasKey || !(aliasKey in args)) {
-        return args;
+    const aliasKey = aliases.find((candidate) => candidate in scalarMappedArgs);
+    if (!aliasKey || !(aliasKey in scalarMappedArgs)) {
+        return scalarMappedArgs;
     }
     return {
-        ...args,
-        [expectedKey]: args[aliasKey],
+        ...scalarMappedArgs,
+        [expectedKey]: scalarMappedArgs[aliasKey],
     };
 }
 export function extractToolCallsFromResult(result) {
@@ -75,12 +101,13 @@ export function extractToolCallsFromResult(result) {
         if (!name) {
             return null;
         }
-        const rawArgs = salvageToolArgs(toolCall.args ?? functionPayload?.arguments) ?? {};
+        const rawArgsInput = toolCall.args ?? functionPayload?.arguments;
+        const rawArgs = salvageToolArgs(rawArgsInput) ?? {};
         if (!isObject(rawArgs)) {
             return null;
         }
         const id = typeof toolCall.id === "string" ? toolCall.id : undefined;
-        return { id, name, args: rawArgs };
+        return { id, name, args: rawArgs, rawArgsInput };
     })
         .filter((item) => item !== null);
 }

package/package.json

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