@botbotgo/agent-harness 0.0.272 → 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.

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`
 
 用于工作区范围的运行时策略。

package/dist/package-version.d.ts

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

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.271";
+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.272",
+  "version": "0.0.273",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",