@botbotgo/agent-harness 0.0.162 → 0.0.164

package/README.md

@@ -26,6 +26,11 @@
   (static page in <code>docs/</code>, publish with GitHub Pages; EN / 中文 toggle)
 </p>
 
+<p align="center">
+  <a href="https://botbotgo.github.io/agent-harness/development/">Developer docs</a>
+  (multi-page static docs in <code>docs/development/</code>)
+</p>
+
 <p align="center">
   <em
     >We specialize in AI solutions. If you have a product idea you want to ship,
@@ -142,6 +147,13 @@ The default rule is:
 
 Boundary documents live in:
 
+- `docs/development/index.html`
+- `docs/development/getting-started.html`
+- `docs/development/application-model.html`
+- `docs/development/workspace-and-yaml.html`
+- `docs/development/extensions.html`
+- `docs/development/runtime-operations.html`
+- `docs/development/testing-and-release.html`
 - `docs/upstream-feature-matrix.md`
 - `docs/product-boundary.md`
 - `docs/runtime-blueprint-assessment.md`
@@ -578,6 +590,7 @@ Example workspaces:
 
 Workspace-local tool modules in `resources/tools/` should be exported with `tool({...})`.
 Any other local module shape is not supported, and unsupported shapes are rejected at load time.
+When a local function tool declares its schema in the module, runtime governance treats that module-defined schema as the source of truth; duplicating it into YAML `inputSchema.ref` is optional rather than required for schema-bound metadata.
 When local tools use Zod-authored schemas, keep the workspace or isolated `resources` package on `zod@^4` so raw-shape validators and runtime parsing stay on one supported major version.
 
 Default wiring guidance:

package/README.zh.md

@@ -26,6 +26,11 @@
   （<code>docs/</code> 中的静态页，通过 GitHub Pages 发布；支持中英文切换）
 </p>
 
+<p align="center">
+  <a href="https://botbotgo.github.io/agent-harness/development/">开发文档</a>
+  （多页面静态文档位于 <code>docs/development/</code>）
+</p>
+
 <p align="center">
   <em
     >我们专注于 AI 解决方案。若有希望落地的产品想法，欢迎来信
@@ -142,6 +147,13 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 
 边界说明见：
 
+- `docs/development/index.html`
+- `docs/development/getting-started.html`
+- `docs/development/application-model.html`
+- `docs/development/workspace-and-yaml.html`
+- `docs/development/extensions.html`
+- `docs/development/runtime-operations.html`
+- `docs/development/testing-and-release.html`
 - `docs/upstream-feature-matrix.md`
 - `docs/product-boundary.md`
 - `docs/runtime-blueprint-assessment.md`
@@ -542,6 +554,7 @@ await stop(runtime);
 
 `resources/tools/` 下的工作区本地工具模块应统一用 `tool({...})` 导出。
 不支持历史/兼容写法，任何不带该导出形式的工具模块都会在工作区加载时被拒绝。
+本地 function tool 如果在模块里声明了 schema，runtime governance 会直接把该模块 schema 视为事实来源；不需要为了 schema-bound 元数据再额外复制一份 YAML `inputSchema.ref`。
 若本地工具使用 Zod schema，请让工作区或隔离的 `resources` 包统一使用 `zod@^4`，避免 raw shape validator 与 runtime 解析落在不同 major 版本上。
 
 主要有三层配置：

package/dist/contracts/workspace.d.ts

@@ -83,6 +83,7 @@ export type ParsedToolObject = {
     config?: Record<string, unknown>;
     subprocess?: boolean;
     inputSchemaRef?: string;
+    hasModuleSchema?: boolean;
     embeddingModelRef?: string;
     backendOperation?: string;
     mcpRef?: string;
@@ -132,6 +133,7 @@ export type CompiledTool = {
     config?: Record<string, unknown>;
     subprocess?: boolean;
     inputSchemaRef?: string;
+    hasModuleSchema?: boolean;
     embeddingModelRef?: string;
     backendOperation?: string;
     mcpRef?: string;

package/dist/extensions.js

@@ -124,6 +124,7 @@ registerToolKind({
                 config: tool.config,
                 subprocess: tool.subprocess,
                 inputSchemaRef: tool.inputSchemaRef,
+                hasModuleSchema: tool.hasModuleSchema,
                 embeddingModelRef: tool.embeddingModelRef,
                 bundleRefs: [],
                 hitl: tool.hitl
@@ -158,6 +159,7 @@ registerToolKind({
                 config: tool.config,
                 subprocess: tool.subprocess,
                 inputSchemaRef: tool.inputSchemaRef,
+                hasModuleSchema: tool.hasModuleSchema,
                 embeddingModelRef: tool.embeddingModelRef,
                 backendOperation: tool.backendOperation,
                 bundleRefs: [],
@@ -193,6 +195,7 @@ registerToolKind({
                 config: tool.config,
                 subprocess: tool.subprocess,
                 inputSchemaRef: tool.inputSchemaRef,
+                hasModuleSchema: tool.hasModuleSchema,
                 embeddingModelRef: tool.embeddingModelRef,
                 mcpRef: tool.mcpRef,
                 bundleRefs: [],
@@ -234,6 +237,7 @@ registerToolKind({
                 config: tool.config,
                 subprocess: tool.subprocess,
                 inputSchemaRef: tool.inputSchemaRef,
+                hasModuleSchema: tool.hasModuleSchema,
                 embeddingModelRef: tool.embeddingModelRef,
                 bundleRefs: [],
                 hitl: tool.hitl

package/dist/package-version.d.ts

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

package/dist/package-version.js

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

package/dist/runtime/harness/bindings.js

@@ -1,6 +1,7 @@
 import { resolveBindingTimeout, resolveProviderRetryPolicy, resolveStreamIdleTimeout } from "../adapter/resilience.js";
 import { toolRequiresRuntimeApproval } from "../adapter/tool/tool-hitl.js";
 import { getBindingPrimaryTools } from "../support/compiled-binding.js";
+import { compiledToolHasInputSchema } from "./tool-schema.js";
 export function getWorkspaceBinding(workspace, agentId) {
     return workspace.bindings.get(agentId);
 }
@@ -29,7 +30,7 @@ export function projectBindingToolExecutionPolicy(binding) {
         toolId: tool.id,
         name: tool.name,
         retryable: tool.retryable === true,
-        hasInputSchema: typeof tool.inputSchemaRef === "string" && tool.inputSchemaRef.trim().length > 0,
+        hasInputSchema: compiledToolHasInputSchema(tool),
         requiresApproval: toolRequiresRuntimeApproval(tool),
     }));
     const retryableToolCount = projectedTools.filter((tool) => tool.retryable).length;

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

@@ -1,5 +1,6 @@
 import { getBindingPrimaryTools } from "../../support/compiled-binding.js";
 import { toolRequiresRuntimeApproval } from "../../adapter/tool/tool-hitl.js";
+import { compiledToolHasInputSchema } from "../tool-schema.js";
 const WRITE_LIKE_PATTERN = /\b(write|edit|delete|create|update|append|insert|push|commit|publish|send|post|apply|merge|sync|upload|save)\b/i;
 function inputHints(binding, tool) {
     const hints = new Set();
@@ -173,7 +174,7 @@ export function buildRuntimeGovernanceBundles(binding) {
             }),
             requiresApproval,
             approvalPolicy: tool.hitl?.enabled === true ? "explicit-hitl" : requiresApproval ? "runtime-default" : "none",
-            hasInputSchema: typeof tool.inputSchemaRef === "string" && tool.inputSchemaRef.trim().length > 0,
+            hasInputSchema: compiledToolHasInputSchema(tool),
             inputRiskHints: inputHints(binding, tool),
         };
     })));

package/dist/runtime/harness/tool-schema.d.ts

@@ -0,0 +1,2 @@
+import type { CompiledTool } from "../../contracts/types.js";
+export declare function compiledToolHasInputSchema(tool: Pick<CompiledTool, "inputSchemaRef" | "hasModuleSchema">): boolean;

package/dist/runtime/harness/tool-schema.js

@@ -0,0 +1,3 @@
+export function compiledToolHasInputSchema(tool) {
+    return (typeof tool.inputSchemaRef === "string" && tool.inputSchemaRef.trim().length > 0) || tool.hasModuleSchema === true;
+}

package/dist/tool-modules.d.ts

@@ -4,6 +4,7 @@ export type LoadedToolModule = {
     implementationName: string;
     invoke: (input: unknown, context?: Record<string, unknown>) => Promise<unknown> | unknown;
     schema: ReturnType<typeof normalizeToolSchema>;
+    hasModuleSchema: boolean;
     description: string;
     retryable?: boolean;
     memory?: {

package/dist/tool-modules.js

@@ -20,6 +20,7 @@ function loadToolObjectDefinition(imported, exportName) {
         implementationName: definition.name?.trim() || exportName,
         invoke: definition.invoke,
         schema: normalizeToolSchema(definition.schema),
+        hasModuleSchema: true,
         description: definition.description.trim(),
         retryable: definition.retryable === true,
         ...(definition.memory ? { memory: { ...definition.memory } } : {}),

package/dist/workspace/object-loader.js

@@ -4,7 +4,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { resolveIsolatedResourceModulePath } from "../resource/isolation.js";
 import { isExternalSourceLocator, resolveResourcePackageRoot } from "../resource/sources.js";
-import { discoverToolModuleDefinitions, isSupportedToolModulePath } from "../tool-modules.js";
+import { discoverToolModuleDefinitions, isSupportedToolModulePath, loadToolModuleDefinition } from "../tool-modules.js";
 import { fileExists } from "../utils/fs.js";
 import { readNamedYamlItems, readYamlItems, } from "./yaml-object-reader.js";
 export { normalizeYamlItem, readYamlItems } from "./yaml-object-reader.js";
@@ -633,12 +633,22 @@ async function readModuleToolItems(root) {
             if (inferredType === "function" && !discoveredPath) {
                 throw new Error(`Module tool ${workspaceObject.id} must define implementation.path or provide index.mjs|index.js|index.cjs`);
             }
+            const implementationName = typeof normalizedItem.implementationName === "string" && normalizedItem.implementationName.trim().length > 0
+                ? normalizedItem.implementationName.trim()
+                : typeof implementation?.export === "string" && implementation.export.trim().length > 0
+                    ? implementation.export.trim()
+                    : workspaceObject.id;
+            const schemaMetadata = inferredType === "function" && discoveredPath
+                ? await readModuleToolSchemaMetadata({
+                    sourcePath: discoveredPath,
+                    implementationName,
+                })
+                : { hasModuleSchema: false };
             records.push({
                 item: {
                     ...normalizedItem,
-                    ...(typeof implementation?.export === "string" && !normalizedItem.implementationName
-                        ? { implementationName: implementation.export }
-                        : {}),
+                    ...(typeof implementation?.export === "string" && !normalizedItem.implementationName ? { implementationName } : {}),
+                    ...(schemaMetadata.hasModuleSchema ? { hasModuleSchema: true } : {}),
                 },
                 sourcePath: discoveredPath ?? sourcePath,
             });
@@ -646,6 +656,32 @@ async function readModuleToolItems(root) {
     }
     return records;
 }
+function findToolPackageRoot(startPath) {
+    let current = path.dirname(startPath);
+    for (;;) {
+        const packageJsonPath = path.join(current, "package.json");
+        if (existsSync(packageJsonPath)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return path.dirname(startPath);
+        }
+        current = parent;
+    }
+}
+async function readModuleToolSchemaMetadata(input) {
+    if (!isSupportedToolModulePath(input.sourcePath)) {
+        return { hasModuleSchema: false };
+    }
+    const packageRoot = findToolPackageRoot(input.sourcePath);
+    const isolatedSourcePath = await resolveIsolatedResourceModulePath(packageRoot, input.sourcePath);
+    const imported = await import(pathToFileURL(isolatedSourcePath).href);
+    const definition = loadToolModuleDefinition(imported, input.implementationName);
+    return {
+        hasModuleSchema: definition.hasModuleSchema,
+    };
+}
 async function loadModuleObjectsForRoot(root, mergedObjects) {
     for (const { item, sourcePath } of await readModuleToolItems(root)) {
         const workspaceObject = parseWorkspaceObject(item, sourcePath);
@@ -728,6 +764,7 @@ export async function readToolModuleItems(root) {
                     name: definition.implementationName,
                     description: definition.description,
                     implementationName: definition.implementationName,
+                    hasModuleSchema: definition.hasModuleSchema,
                     ...(definition.retryable !== undefined ? { retryable: definition.retryable } : {}),
                     ...(definition.memory ? { config: { memory: definition.memory } } : {}),
                 },

package/dist/workspace/resource-compilers.js

@@ -269,6 +269,7 @@ export function parseToolObject(object) {
             : undefined),
         subprocess: value.subprocess === true,
         inputSchemaRef: typeof asObject(value.inputSchema)?.ref === "string" ? String(asObject(value.inputSchema)?.ref) : undefined,
+        hasModuleSchema: value.hasModuleSchema === true,
         embeddingModelRef: typeof value.embeddingModelRef === "string"
             ? value.embeddingModelRef
             : typeof value.embeddingModel === "string"

package/package.json

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