@botbotgo/agent-harness 0.0.271 → 0.0.273

package/README.md

@@ -704,6 +704,7 @@ Discovery rules:
 Example workspaces:
 
 - `examples/hello-skill-app/` keeps the smallest local tool + skill workspace
+- `examples/local-scheduled-task-app/` runs recurring prompt-driven tasks with a local `node-llama-cpp` GGUF workspace and one local tool
 - `examples/multimodal-app/` keeps the smallest image-plus-PDF example and sends both through one `request(...)` call
 - `examples/plan-and-run-app/` keeps the smallest public-API planning example and prints both the plan and the observed execution steps
 - `examples/runtime-flow-demo/` runs one real hosted-model request and exports a Mermaid flowchart from runtime plus upstream events
@@ -743,6 +744,13 @@ Practical guidance:
 - use `backend: deepagent` for approvals, resume, multi-agent orchestration, rich memory flows, and heavier tool chains
 - keep `backend: langchain-v1` for lighter direct-response or explicitly chosen V1 agent shapes while this upstream behavior settles
 
+Local GGUF note:
+
+- `provider: node-llama-cpp` now exposes a LangChain-style tool-binding shim, so local GGUF models can enter the standard tool-calling path without an app-owned model wrapper
+- `backend: langchain-v1` is the straightforward local GGUF path and is the currently verified default for `node-llama-cpp` tool use
+- `backend: deepagent` can also reach the same tool-calling path, but final reliability still depends on the selected model following upstream tool schemas correctly
+- `agent-harness` does not try to normalize every model-specific argument drift or malformed tool payload; once the runtime hands a call to upstream tools, schema fidelity is a model responsibility
+
 ### `config/runtime/workspace.yaml`
 
 Use this file for workspace-wide runtime policy.
@@ -1059,6 +1067,7 @@ 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.
 - ACP transport validation now covers the reference-client core flow: capability discovery, request submit, session lookup, request lookup, invalid-JSON handling, notification calls without response ids, stdio JSON-RPC, and HTTP plus SSE runtime notifications.
+- Cross-protocol conformance now has an explicit regression gate as well: ACP submission, A2A task lookup and continuation, and runtime MCP inspection must all project the same persisted `sessionId` / `requestId` runtime records instead of drifting into surface-specific identifiers or side stores.
 - For the thinnest editor or CLI starter, begin with `agent-harness acp serve --workspace . --transport stdio` and mirror the `examples/protocol-hello-world/app/acp-stdio-hello-world.mjs` wire shape. Applications that want an in-process reference client can use `createAcpStdioClient(...)` to issue JSON-RPC requests and route runtime notifications without hand-rolling line parsing.
 - `serveA2aHttp(runtime)` exposes an A2A-compatible HTTP JSON-RPC bridge plus agent card discovery, mapping both existing methods such as `message/send` and A2A v1.0 PascalCase methods such as `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, `GetAgentCard`, `GetExtendedAgentCard`, and task push-notification config methods onto the existing session/request runtime surface. The bridge now advertises both `1.0` and `0.3` JSON-RPC interfaces, answers `HEAD` / `OPTIONS` discovery on the agent-card path, sets supported-version discovery headers, can optionally expose registry URLs plus detached signed-card metadata for surrounding discovery systems, validates `A2A-Version`, records `A2A-Extensions` into runtime invocation metadata, publishes `TASK_STATE_*` statuses plus the `{ task }` `SendMessage` wrapper, streams an initial `{ task }` snapshot plus later `{ statusUpdate }` payloads over SSE for v1 streaming methods, and can send best-effort webhook task snapshots for configured push notification receivers.
 - `serveAgUiHttp(runtime)` exposes an AG-UI-compatible HTTP SSE bridge that projects runtime lifecycle, text output, upstream thinking, step progress, and tool calls onto `RUN_*`, `TEXT_MESSAGE_*`, `THINKING_TEXT_MESSAGE_*`, `STEP_*`, and `TOOL_CALL_*` events for UI clients.

package/README.zh.md

@@ -667,6 +667,7 @@ await stop(runtime);
 示例工作区：
 
 - `examples/hello-skill-app/` 保留最小的本地 tool + skill 工作区
+- `examples/local-scheduled-task-app/` 展示如何用本地 `node-llama-cpp` GGUF 工作区和一个本地 tool 执行周期性 prompt 任务
 - `examples/multimodal-app/` 保留最小的图片 + PDF 示例，并通过一次 `request(...)` 调用发送
 - `examples/plan-and-run-app/` 保留最小的公开 API 规划示例，并同时打印规划步骤和真实执行步骤
 - `examples/runtime-flow-demo/` 会跑一次真实 hosted model 请求，并把 runtime 与 upstream events 导出为 Mermaid flowchart
@@ -700,6 +701,13 @@ await stop(runtime);
 - approvals、resume、多 agent orchestration、复杂 memory 流、重工具链，优先使用 `backend: deepagent`
 - `backend: langchain-v1` 先保留给轻量 direct-response 场景，或明确需要 V1 agent 语义的工作区
 
+本地 GGUF 补充说明：
+
+- `provider: node-llama-cpp` 现在带有一层 LangChain 风格的 tool-binding shim，因此本地 GGUF 模型可以进入标准 tool-calling 路径，而不需要应用自己包一层 model wrapper
+- 对 `node-llama-cpp` 来说，`backend: langchain-v1` 仍然是更直接、当前已验证的本地 tool use 路径
+- `backend: deepagent` 也可以走到同一条 tool-calling 路径，但最终稳定性仍取决于所选模型是否能正确遵守 upstream tool schema
+- `agent-harness` 不会为每个模型的参数漂移或畸形 tool payload 做无限兼容；runtime 把调用交给 upstream tools 之后，schema fidelity 就属于模型责任
+
 ### `config/runtime/workspace.yaml`
 
 用于工作区范围的运行时策略。
@@ -1016,6 +1024,7 @@ ACP transport 说明：
 - `serveAcpStdio(runtime)` 提供基于 stdio 的 newline-delimited JSON-RPC，适合本地 IDE、CLI 或子进程客户端。
 - `serveAcpHttp(runtime)` 提供基于 HTTP 的 JSON-RPC 与 SSE runtime events，适合远程界面或独立控制面接入。
 - ACP transport 现已覆盖核心参考客户端流程验证：capability discovery、request submit、session lookup、request lookup、invalid JSON 处理、无 id notification 不返回响应，以及 stdio JSON-RPC 与 HTTP + SSE runtime notifications。
+- 现在还额外有一条跨协议一致性回归门：ACP 发起的 request、A2A 读取或继续的 task，以及 runtime MCP 暴露的检查结果，必须始终指向同一组持久化 `sessionId` / `requestId` 运行时记录，不能漂移成各协议各自维护的标识体系。
 - 如果要从最薄的一层 editor / CLI starter 开始，优先用 `agent-harness acp serve --workspace . --transport stdio`，并直接参考 `examples/protocol-hello-world/app/acp-stdio-hello-world.mjs` 的 wire shape。需要在应用内使用 reference client 时，可直接用 `createAcpStdioClient(...)` 发起 JSON-RPC 请求并分流 runtime notifications，避免每个 sidecar 自己重写 line parsing。
 - `serveA2aHttp(runtime)` 提供 A2A HTTP JSON-RPC bridge 与 agent card discovery，同时兼容 `message/send` 这类旧方法，以及 `SendMessage`、`SendStreamingMessage`、`GetTask`、`ListTasks`、`CancelTask`、`SubscribeToTask`、`GetAgentCard`、`GetExtendedAgentCard` 与 task push-notification config 这类 A2A v1.0 方法，并统一映射到现有 session/request 运行记录。bridge 现在会同时声明 `1.0` 与 `0.3` 两个 JSON-RPC interface、在 agent card 路径上响应 `HEAD` / `OPTIONS` discovery、写出支持版本的 discovery headers、可选暴露 registry URL 与 detached signed-card metadata 供外围发现系统使用、校验 `A2A-Version`、把 `A2A-Extensions` 记录进 runtime invocation metadata、发布 `TASK_STATE_*` 状态与 `SendMessage` 的 `{ task }` wrapper、在 v1 streaming 方法上先通过 SSE 输出 `{ task }` 初始快照，再输出 `{ statusUpdate }` 增量状态，并可向已配置的 webhook receiver 发送 best-effort task push notifications。
 - `serveAgUiHttp(runtime)` 提供 AG-UI HTTP SSE bridge，把 runtime 生命周期、文本输出、upstream thinking、step 进度与 tool call 投影成 `RUN_*`、`TEXT_MESSAGE_*`、`THINKING_TEXT_MESSAGE_*`、`STEP_*` 与 `TOOL_CALL_*` 事件，便于 UI 客户端直接接入。

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.270";
+export declare const AGENT_HARNESS_VERSION = "0.0.272";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.270";
+export const AGENT_HARNESS_VERSION = "0.0.272";

package/dist/runtime/adapter/model/model-providers.js

@@ -2,8 +2,324 @@ import { ChatAnthropic } from "@langchain/anthropic";
 import { ChatGoogle } from "@langchain/google";
 import { ChatOllama } from "@langchain/ollama";
 import { ChatOpenAI } from "@langchain/openai";
+import { AIMessage } from "langchain";
 import { initChatModel } from "langchain";
+import { salvageToolArgs, tryParseJson } from "../../parsing/output-parsing.js";
+import { normalizeModelFacingToolSchema } from "../tool/resolved-tool.js";
 import { normalizeOpenAICompatibleInit } from "../compat/openai-compatible.js";
+const NODE_LLAMA_CPP_TOOL_CALL_INSTRUCTION = [
+    "Available tools are listed below.",
+    "If you need a tool, respond with only one JSON object.",
+    'Use this exact shape: {"name":"tool_name","arguments":{"key":"value"}}',
+    "Do not add markdown, prose, or code fences unless the output is wrapped inside <tool_call>...</tool_call>.",
+    "If no tool is needed, answer normally.",
+].join("\n");
+function readModelText(value) {
+    if (typeof value === "string") {
+        return value.trim();
+    }
+    if (typeof value !== "object" || value === null) {
+        return "";
+    }
+    const typed = value;
+    if (typeof typed.content === "string") {
+        return typed.content.trim();
+    }
+    if (Array.isArray(typed.content)) {
+        return typed.content
+            .map((item) => typeof item === "string"
+            ? item
+            : typeof item === "object" && item !== null && typeof item.text === "string"
+                ? item.text
+                : "")
+            .join("")
+            .trim();
+    }
+    return "";
+}
+function readPromptContent(value) {
+    if (typeof value === "string") {
+        return value.trim();
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => readPromptContent(item)).filter(Boolean).join("\n").trim();
+    }
+    if (typeof value !== "object" || value === null) {
+        return "";
+    }
+    if (typeof value.content === "string" || Array.isArray(value.content)) {
+        return readModelText(value);
+    }
+    if (typeof value.text === "string") {
+        return String(value.text).trim();
+    }
+    return "";
+}
+function readMessageType(value) {
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    if (typeof value._getType === "function") {
+        return String(value._getType() ?? "");
+    }
+    if (typeof value.getType === "function") {
+        return String(value.getType() ?? "");
+    }
+    const ids = Array.isArray(value.id)
+        ? (value.id).filter((item) => typeof item === "string")
+        : [];
+    const typeName = ids.at(-1);
+    if (typeName === "HumanMessage")
+        return "human";
+    if (typeName === "SystemMessage")
+        return "system";
+    if (typeName === "AIMessage")
+        return "ai";
+    if (typeName === "ToolMessage")
+        return "tool";
+    return undefined;
+}
+function mapMessageRole(value) {
+    const directRole = typeof value?.role === "string"
+        ? String(value.role).trim().toLowerCase()
+        : undefined;
+    if (directRole) {
+        if (directRole === "assistant")
+            return "ASSISTANT";
+        if (directRole === "tool")
+            return "TOOL";
+        return directRole.toUpperCase();
+    }
+    const messageType = readMessageType(value);
+    if (messageType === "system")
+        return "SYSTEM";
+    if (messageType === "human")
+        return "USER";
+    if (messageType === "ai")
+        return "ASSISTANT";
+    if (messageType === "tool")
+        return "TOOL";
+    return "USER";
+}
+function readToolCalls(value) {
+    if (typeof value !== "object" || value === null) {
+        return [];
+    }
+    if (Array.isArray(value.tool_calls)) {
+        return value.tool_calls;
+    }
+    if (typeof value.kwargs === "object" && value.kwargs !== null) {
+        const toolCalls = value.kwargs.tool_calls;
+        return Array.isArray(toolCalls) ? toolCalls : [];
+    }
+    return [];
+}
+function formatStructuredMessage(value) {
+    const role = mapMessageRole(value);
+    const content = readPromptContent(value);
+    if (role === "ASSISTANT") {
+        const toolCalls = readToolCalls(value);
+        if (toolCalls.length > 0) {
+            return [
+                "ASSISTANT_TOOL_CALLS:",
+                JSON.stringify(toolCalls),
+            ].join("\n");
+        }
+    }
+    if (role === "TOOL") {
+        const typed = value;
+        const name = typeof typed.name === "string"
+            ? typed.name
+            : typeof typed.kwargs === "object" && typed.kwargs !== null && typeof typed.kwargs.name === "string"
+                ? String(typed.kwargs.name)
+                : typeof typed.lc_kwargs === "object" && typed.lc_kwargs !== null && typeof typed.lc_kwargs.name === "string"
+                    ? String(typed.lc_kwargs.name)
+                    : "";
+        const toolCallId = typeof typed.tool_call_id === "string"
+            ? typed.tool_call_id
+            : typeof typed.kwargs === "object" && typed.kwargs !== null && typeof typed.kwargs.tool_call_id === "string"
+                ? String(typed.kwargs.tool_call_id)
+                : typeof typed.lc_kwargs === "object" && typed.lc_kwargs !== null && typeof typed.lc_kwargs.tool_call_id === "string"
+                    ? String(typed.lc_kwargs.tool_call_id)
+                    : "";
+        return [
+            "TOOL_RESULT:",
+            name ? `name=${name}` : "",
+            toolCallId ? `tool_call_id=${toolCallId}` : "",
+            content,
+        ].filter(Boolean).join("\n");
+    }
+    return content ? `${role}:\n${content}` : "";
+}
+function stringifyNodeLlamaCppInput(input) {
+    if (typeof input === "string") {
+        return input;
+    }
+    if (Array.isArray(input)) {
+        return input
+            .map((message) => formatStructuredMessage(message))
+            .filter(Boolean)
+            .join("\n\n")
+            .trim();
+    }
+    if (typeof input === "object" && input !== null && Array.isArray(input.messages)) {
+        return stringifyNodeLlamaCppInput(input.messages);
+    }
+    return readPromptContent(input);
+}
+function extractToolCallPayload(text) {
+    const trimmed = text.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const direct = tryParseJson(trimmed);
+    if (direct) {
+        return direct;
+    }
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim();
+    if (fenced) {
+        const parsed = tryParseJson(fenced);
+        if (parsed) {
+            return parsed;
+        }
+    }
+    const xml = trimmed.match(/<tool_call>\s*([\s\S]*?)\s*<\/tool_call>/i)?.[1]?.trim();
+    if (xml) {
+        const parsed = tryParseJson(xml);
+        if (parsed) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function normalizeParsedToolCall(payload) {
+    if (typeof payload !== "object" || payload === null) {
+        return null;
+    }
+    if (Array.isArray(payload)) {
+        return normalizeParsedToolCall(payload[0]);
+    }
+    const typed = payload;
+    const functionPayload = typeof typed.function === "object" && typed.function !== null ? typed.function : undefined;
+    const nameCandidate = typed.name ?? typed.tool ?? functionPayload?.name;
+    const name = typeof nameCandidate === "string" ? nameCandidate.trim() : "";
+    if (!name) {
+        return null;
+    }
+    const argsCandidate = typed.arguments ?? typed.args ?? typed.parameters ?? typed.input ?? functionPayload?.arguments ?? {};
+    const args = salvageToolArgs(argsCandidate) ?? {};
+    return { name, args };
+}
+function formatBoundToolInstruction(tool) {
+    if (typeof tool !== "object" || tool === null) {
+        return null;
+    }
+    const typed = tool;
+    const name = typeof typed.name === "string" ? typed.name.trim() : "";
+    if (!name) {
+        return null;
+    }
+    const description = typeof typed.description === "string" ? typed.description.trim() : "";
+    const schema = normalizeModelFacingToolSchema(typed);
+    return [
+        `Tool: ${name}`,
+        description ? `Description: ${description}` : "",
+        `Arguments JSON schema: ${JSON.stringify(schema)}`,
+    ].filter(Boolean).join("\n");
+}
+function withNodeLlamaCppToolPrompt(input, tools) {
+    const toolInstructions = tools.map((tool) => formatBoundToolInstruction(tool)).filter((value) => Boolean(value));
+    if (toolInstructions.length === 0) {
+        return stringifyNodeLlamaCppInput(input);
+    }
+    const systemContent = `${NODE_LLAMA_CPP_TOOL_CALL_INSTRUCTION}\n\n${toolInstructions.join("\n\n")}`;
+    const prompt = stringifyNodeLlamaCppInput(input);
+    return [systemContent, prompt].filter(Boolean).join("\n\n");
+}
+function createNodeLlamaCppToolBindableModel(model, boundTools = []) {
+    return new Proxy(model, {
+        has(target, prop) {
+            if (prop === "bindTools" || prop === "invoke" || prop === "stream" || prop === "withConfig") {
+                return true;
+            }
+            return prop in target;
+        },
+        get(target, prop, receiver) {
+            if (prop === "bindTools") {
+                return (tools) => createNodeLlamaCppToolBindableModel(target, tools);
+            }
+            if (prop === "invoke") {
+                return async (input, config) => {
+                    const rawResult = await target.invoke(boundTools.length > 0 ? withNodeLlamaCppToolPrompt(input, boundTools) : input, config);
+                    if (boundTools.length === 0) {
+                        return rawResult;
+                    }
+                    const text = readModelText(rawResult);
+                    const parsedToolCall = normalizeParsedToolCall(extractToolCallPayload(text));
+                    if (!parsedToolCall) {
+                        return rawResult;
+                    }
+                    return new AIMessage({
+                        content: "",
+                        tool_calls: [{
+                                id: `tool-${Math.random().toString(36).slice(2, 10)}`,
+                                name: parsedToolCall.name,
+                                args: parsedToolCall.args,
+                                type: "tool_call",
+                            }],
+                    });
+                };
+            }
+            if (prop === "stream") {
+                return async (input, config) => {
+                    const value = await receiver.invoke(input, config);
+                    return (async function* () {
+                        yield value;
+                    })();
+                };
+            }
+            if (prop === "withConfig" && typeof target.withConfig === "function") {
+                return (config) => createNodeLlamaCppToolBindableModel(target.withConfig(config), boundTools);
+            }
+            const member = Reflect.get(target, prop, receiver);
+            return typeof member === "function" ? member.bind(target) : member;
+        },
+        getOwnPropertyDescriptor(target, prop) {
+            if (prop === "bindTools" || prop === "invoke" || prop === "stream" || prop === "withConfig") {
+                return {
+                    configurable: true,
+                    enumerable: false,
+                    writable: false,
+                    value: this.get?.(target, prop, target),
+                };
+            }
+            return Reflect.getOwnPropertyDescriptor(target, prop);
+        },
+    });
+}
+function inferNodeLlamaCppModelPath(model) {
+    const modelPath = typeof model.init?.modelPath === "string" ? model.init.modelPath.trim() : "";
+    if (modelPath) {
+        return modelPath;
+    }
+    return model.model.includes("/") || model.model.endsWith(".gguf") ? model.model : undefined;
+}
+async function createNodeLlamaCppModel(model) {
+    const modelPath = inferNodeLlamaCppModelPath(model);
+    if (!modelPath) {
+        throw new Error(`Model ${model.id} with provider ${model.provider} must define a GGUF path via top-level modelPath or use model as the GGUF path.`);
+    }
+    try {
+        const { ChatLlamaCpp } = await import("@langchain/community/chat_models/llama_cpp");
+        return createNodeLlamaCppToolBindableModel(await ChatLlamaCpp.initialize({
+            ...model.init,
+            modelPath,
+        }));
+    }
+    catch (error) {
+        throw new Error(`Failed to initialize ${model.provider} model ${model.id}. Install node-llama-cpp in the application workspace and ensure the GGUF file exists at ${modelPath}.`, { cause: error });
+    }
+}
 export async function createResolvedModel(model, modelResolver) {
     if (modelResolver) {
         return modelResolver(model.id);
@@ -23,5 +339,8 @@ export async function createResolvedModel(model, modelResolver) {
     if (model.provider === "google" || model.provider === "google-genai" || model.provider === "gemini") {
         return new ChatGoogle({ model: model.model, ...model.init });
     }
+    if (model.provider === "node-llama-cpp" || model.provider === "llama-cpp") {
+        return createNodeLlamaCppModel(model);
+    }
     return initChatModel(model.model, { modelProvider: model.provider, ...model.init });
 }

package/dist/runtime/support/embedding-models.js

@@ -46,6 +46,29 @@ function normalizeOpenAICompatibleInit(init) {
     delete normalized.omitAuthHeader;
     return normalized;
 }
+function inferNodeLlamaCppModelPath(embeddingModel) {
+    const modelPath = typeof embeddingModel.init?.modelPath === "string" ? embeddingModel.init.modelPath.trim() : "";
+    if (modelPath) {
+        return modelPath;
+    }
+    return embeddingModel.model.includes("/") || embeddingModel.model.endsWith(".gguf") ? embeddingModel.model : undefined;
+}
+async function createNodeLlamaCppEmbeddings(embeddingModel) {
+    const modelPath = inferNodeLlamaCppModelPath(embeddingModel);
+    if (!modelPath) {
+        throw new Error(`Embedding model ${embeddingModel.id} with provider ${embeddingModel.provider} must define a GGUF path via top-level modelPath or use model as the GGUF path.`);
+    }
+    try {
+        const { LlamaCppEmbeddings } = await import("@langchain/community/embeddings/llama_cpp");
+        return await LlamaCppEmbeddings.initialize({
+            ...embeddingModel.init,
+            modelPath,
+        });
+    }
+    catch (error) {
+        throw new Error(`Failed to initialize ${embeddingModel.provider} embedding model ${embeddingModel.id}. Install node-llama-cpp in the application workspace and ensure the GGUF file exists at ${modelPath}.`, { cause: error });
+    }
+}
 export function resolveCompiledEmbeddingModelRef(workspace, embeddingModelRef) {
     const resolvedId = embeddingModelRef ? resolveRefId(embeddingModelRef) : "default";
     const embeddingModel = workspace.embeddings.get(resolvedId);
@@ -85,5 +108,8 @@ export async function resolveCompiledEmbeddingModel(embeddingModel, resolver) {
     if (embeddingModel.provider === "llamaindex-ollama") {
         return createLlamaIndexEmbeddingModel(embeddingModel);
     }
-    throw new Error(`Embedding model provider ${embeddingModel.provider} is not supported by the built-in runtime. Configure embeddingModelResolver or use openai-compatible/openai/ollama/llamaindex-ollama.`);
+    if (embeddingModel.provider === "node-llama-cpp" || embeddingModel.provider === "llama-cpp") {
+        return createNodeLlamaCppEmbeddings(embeddingModel);
+    }
+    throw new Error(`Embedding model provider ${embeddingModel.provider} is not supported by the built-in runtime. Configure embeddingModelResolver or use openai-compatible/openai/ollama/llamaindex-ollama/node-llama-cpp.`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.271",
+  "version": "0.0.273",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",