@botbotgo/agent-harness 0.0.135 → 0.0.136

package/README.md

@@ -423,13 +423,12 @@ kind: Agent
 metadata:
   name: orchestra
 spec:
-  execution:
-    backend: deepagent
-    modelRef: model/default
-    mcpServers:
-      - name: browser
-        command: node
-        args: ["./mcp-browser-server.mjs"]
+  backend: deepagent
+  modelRef: model/default
+  mcpServers:
+    - name: browser
+      command: node
+      args: ["./mcp-browser-server.mjs"]
 ```
 
 Expose harness tools as an MCP server:
@@ -478,7 +477,8 @@ Any other local module shape is not supported, and unsupported shapes are reject
 
 Default wiring guidance:
 
-- prefer agent-local wiring for workspace-owned function tools
+- let workspace startup scan local and attached `resources` packages into one registry
+- let agents whitelist tools and skills by name
 - keep `config/catalogs/tools.yaml` for reusable shared tools
 - keep `config/catalogs/mcp.yaml` for shared MCP server definitions
 - let agents select MCP tools and apply per-usage MCP overrides where needed
@@ -635,7 +635,7 @@ Use this file for reusable tool objects.
 
 Built-in tool families include function tools, backend tools, MCP tools, bundles, and provider-native tools. Provider-native tools are declared in YAML and resolved directly to upstream factories.
 
-For workspace-owned function tools, prefer agent-side wiring first. Keep `config/catalogs/tools.yaml` for reusable shared tool objects rather than making it the default path for every local tool.
+Keep `config/catalogs/tools.yaml` for reusable shared tool objects rather than making it the default path for every local tool. Workspace-owned function tools should normally be discovered from `resources/tools/` and then whitelisted by name in each agent.
 
 ### `config/catalogs/mcp.yaml`
 
@@ -660,12 +660,12 @@ spec:
 
 ### `config/agents/*.yaml`
 
-Agents always use `kind: Agent` plus `spec.execution.backend`.
+Agents always use `kind: Agent` plus `spec.backend`.
 
-Use two nested sections:
+Use two sections:
 
 - `spec.runtime` for harness-owned runtime placement such as `spec.runtime.runRoot`
-- `spec.execution` for upstream execution semantics and adapter-facing config
+- top-level `spec` fields for upstream execution semantics and adapter-facing config
 
 Example direct host:
 
@@ -677,26 +677,28 @@ metadata:
 spec:
   runtime:
     runRoot: ./.agent
-  execution:
-    backend: langchain-v1
-    modelRef: model/default
-    tools: []
-    skills: []
-    memory: []
-    subagents: []
-    mcpServers: []
-    config:
-      checkpointer:
-        ref: checkpointer/default
-      store:
-        ref: store/default
-      interruptOn: {}
-      filesystem:
-        rootDir: .
-        virtualMode: true
-        maxFileSizeMb: 10
-      middleware: []
-      systemPrompt: Answer simple requests directly.
+  backend: langchain-v1
+  modelRef: model/default
+  tools:
+    - write_file:
+        subprocess: true
+  skills:
+    - code-review
+  memory: []
+  subagents: []
+  mcpServers: []
+  config:
+    checkpointer:
+      ref: checkpointer/default
+    store:
+      ref: store/default
+    interruptOn: {}
+    filesystem:
+      rootDir: .
+      virtualMode: true
+      maxFileSizeMb: 10
+    middleware: []
+    systemPrompt: Answer simple requests directly.
 ```
 
 Example orchestra host:
@@ -709,27 +711,28 @@ metadata:
 spec:
   runtime:
     runRoot: ./.agent
-  execution:
-    backend: deepagent
-    modelRef: model/default
-    memory:
-      - path: config/agent-context.md
-    tools: []
-    skills: []
-    subagents: []
-    mcpServers: []
-    config:
-      store:
-        ref: store/default
-      checkpointer:
-        ref: checkpointer/default
-      backend:
-        ref: backend/default
-      interruptOn: {}
-      middleware: []
+  backend: deepagent
+  modelRef: model/default
+  memory:
+    - path: config/agent-context.md
+  tools:
+    - stock_snapshot
+  skills:
+    - stock-research
+  subagents: []
+  mcpServers: []
+  config:
+    store:
+      ref: store/default
+    checkpointer:
+      ref: checkpointer/default
+    backend:
+      ref: backend/default
+    interruptOn: {}
+    middleware: []
 ```
 
-For backend-specific options, prefer the upstream concept directly inside `spec.execution.config`. Upstream feature coverage is tracked in [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md).
+For backend-specific options, prefer the upstream concept directly inside `spec.config`. Upstream feature coverage is tracked in [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md).
 
 ## Design Notes
 

package/README.zh.md

@@ -423,13 +423,12 @@ kind: Agent
 metadata:
   name: orchestra
 spec:
-  execution:
-    backend: deepagent
-    modelRef: model/default
-    mcpServers:
-      - name: browser
-        command: node
-        args: ["./mcp-browser-server.mjs"]
+  backend: deepagent
+  modelRef: model/default
+  mcpServers:
+    - name: browser
+      command: node
+      args: ["./mcp-browser-server.mjs"]
 ```
 
 将 harness 工具作为 MCP 服务对外暴露：
@@ -478,6 +477,8 @@ await stop(runtime);
 
 主要有三层配置：
 
+- 先由 workspace 启动时扫描本地和附加的 `resources` 包，建立统一 registry
+- agent 再按名字白名单选择 tools 与 skills
 - `config/runtime/workspace.yaml` 中的运行时策略
 - `config/catalogs/*.yaml` 中的可复用对象目录
 - `config/agents/*.yaml` 中的 agent 装配
@@ -625,6 +626,8 @@ spec:
 
 内置工具族包括函数工具、后端工具、MCP 工具、bundle 与原生 provider 工具。原生 provider 工具在 YAML 中声明并直接解析到上游工厂。
 
+`config/catalogs/tools.yaml` 更适合放可复用共享工具对象，而不应成为每个本地工具的默认入口。工作区自有函数工具通常应从 `resources/tools/` 发现，再由各 agent 按名字白名单启用。
+
 ### `config/catalogs/mcp.yaml`
 
 命名 MCP 服务预设。
@@ -646,12 +649,12 @@ spec:
 
 ### `config/agents/*.yaml`
 
-Agent 始终使用 `kind: Agent` 以及 `spec.execution.backend`。
+Agent 始终使用 `kind: Agent` 以及 `spec.backend`。
 
-两个嵌套区块：
+两个区块：
 
 - `spec.runtime`：harness 侧运行时放置，例如 `spec.runtime.runRoot`
-- `spec.execution`：上游执行语义与面向适配器的配置
+- `spec` 顶层字段：上游执行语义与面向适配器的配置
 
 direct 主机示例：
 
@@ -663,26 +666,28 @@ metadata:
 spec:
   runtime:
     runRoot: ./.agent
-  execution:
-    backend: langchain-v1
-    modelRef: model/default
-    tools: []
-    skills: []
-    memory: []
-    subagents: []
-    mcpServers: []
-    config:
-      checkpointer:
-        ref: checkpointer/default
-      store:
-        ref: store/default
-      interruptOn: {}
-      filesystem:
-        rootDir: .
-        virtualMode: true
-        maxFileSizeMb: 10
-      middleware: []
-      systemPrompt: Answer simple requests directly.
+  backend: langchain-v1
+  modelRef: model/default
+  tools:
+    - write_file:
+        subprocess: true
+  skills:
+    - code-review
+  memory: []
+  subagents: []
+  mcpServers: []
+  config:
+    checkpointer:
+      ref: checkpointer/default
+    store:
+      ref: store/default
+    interruptOn: {}
+    filesystem:
+      rootDir: .
+      virtualMode: true
+      maxFileSizeMb: 10
+    middleware: []
+    systemPrompt: Answer simple requests directly.
 ```
 
 orchestra 主机示例：
@@ -695,27 +700,28 @@ metadata:
 spec:
   runtime:
     runRoot: ./.agent
-  execution:
-    backend: deepagent
-    modelRef: model/default
-    memory:
-      - path: config/agent-context.md
-    tools: []
-    skills: []
-    subagents: []
-    mcpServers: []
-    config:
-      store:
-        ref: store/default
-      checkpointer:
-        ref: checkpointer/default
-      backend:
-        ref: backend/default
-      interruptOn: {}
-      middleware: []
+  backend: deepagent
+  modelRef: model/default
+  memory:
+    - path: config/agent-context.md
+  tools:
+    - stock_snapshot
+  skills:
+    - stock-research
+  subagents: []
+  mcpServers: []
+  config:
+    store:
+      ref: store/default
+    checkpointer:
+      ref: checkpointer/default
+    backend:
+      ref: backend/default
+    interruptOn: {}
+    middleware: []
 ```
 
-后端相关选项优先直接写在 `spec.execution.config` 中沿用上游概念。上游能力覆盖见 [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md)。
+后端相关选项优先直接写在 `spec.config` 中沿用上游概念。上游能力覆盖见 [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md)。
 
 ## 设计说明
 

package/dist/config/agents/direct.yaml

@@ -1,7 +1,7 @@
 # agent-harness feature: schema version for this declarative config object.
 apiVersion: agent-harness/v1alpha1
 # agent-harness feature: object type discriminator.
-# Prefer the generic `Agent` form and select the concrete execution backend under `spec.execution`.
+# Prefer the generic `Agent` form and place execution fields directly under `spec`.
 kind: Agent
 metadata:
   # agent-harness feature: stable object id used for refs and host-agent selection.
@@ -19,74 +19,73 @@ spec:
   # =====================
   # Runtime Agent Features
   # =====================
-  execution:
-    # Current backend adapter for this host profile.
-    backend: langchain-v1
-    # Upstream execution feature: model ref for the underlying LLM used by the direct-response agent.
-    # This should point at a cheap, fast, general-purpose chat model, because `direct` is intended
-    # to be the low-latency path for simple requests.
-    modelRef: model/default
-    # Upstream execution feature: direct host starts with no attached explicit tools by default.
-    tools: []
-    # Upstream execution feature: direct host starts with no attached local skill packages by default.
-    skills: []
-    # Upstream execution feature: direct host does not bootstrap project memory by default.
-    memory: []
-    # Upstream execution feature: direct host does not predeclare subagents by default.
-    subagents: []
-    # Upstream execution feature: direct host does not attach MCP servers by default.
-    mcpServers: []
-    # Runtime execution feature: checkpointer config passed into the selected backend adapter.
-    # Even the lightweight direct path can benefit from resumable state during interactive use.
-    # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
-    # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
-    checkpointer:
-      ref: checkpointer/sqlite
-    # Upstream execution feature: LangGraph store available to middleware and runtime context hooks.
-    # The default direct host keeps this enabled so middleware can use the same durable store surface as other hosts.
-    store:
-      ref: store/default
-    # Upstream execution feature: no declarative HITL tool routing by default.
-    interruptOn: {}
-    # Upstream execution feature: filesystem middleware settings for LangChain v1 agents.
-    # This only becomes active when `middleware` includes `{ kind: filesystem }`, or when
-    # automatic upstream middleware such as skills or memory need a filesystem backend.
-    # Keep the default root inside the workspace so file-aware middleware stays bounded.
-    filesystem:
-      rootDir: .
-      virtualMode: true
-      maxFileSizeMb: 10
-    # Upstream execution feature: no extra declarative middleware beyond the runtime's automatic injections.
-    # Common upstream middleware kinds that this harness can compile directly from YAML:
-    # - `filesystem`
-    # - `patchToolCalls`
-    # - `summarization`
-    # - `dynamicSystemPrompt`
-    # - `humanInTheLoop`
-    # - `todoList`
-    # - `pii`, `piiRedaction`
-    #
-    # Keep the default empty so the lightweight direct host stays minimal.
-    middleware: []
-    # Upstream execution feature: system prompt for the lightweight direct-response host.
-    # This prompt should keep the agent focused on:
-    # - answering simple requests in one turn
-    # - staying lightweight instead of planning or orchestrating
-    # - avoiding delegation-heavy decomposition unless the caller explicitly switches agents
-    #
-    # The direct host is intentionally narrower than the orchestra host:
-    # - `direct` is optimized for latency and straightforward completion
-    # - `orchestra` is optimized for multi-step work, tools, and delegation
-    #
-    # Keep this prompt biased toward concise, self-contained answers. If richer routing policy is
-    # needed for choosing between host agents, configure that separately via `Runtime.spec.routing`
-    # rather than overloading the direct host prompt with classifier behavior.
-    systemPrompt: |-
-      You are the direct agent.
+  # Current backend adapter for this host profile.
+  backend: langchain-v1
+  # Upstream execution feature: model ref for the underlying LLM used by the direct-response agent.
+  # This should point at a cheap, fast, general-purpose chat model, because `direct` is intended
+  # to be the low-latency path for simple requests.
+  modelRef: model/default
+  # Upstream execution feature: direct host starts with no attached explicit tools by default.
+  tools: []
+  # Upstream execution feature: direct host starts with no attached local skill packages by default.
+  skills: []
+  # Upstream execution feature: direct host does not bootstrap project memory by default.
+  memory: []
+  # Upstream execution feature: direct host does not predeclare subagents by default.
+  subagents: []
+  # Upstream execution feature: direct host does not attach MCP servers by default.
+  mcpServers: []
+  # Runtime execution feature: checkpointer config passed into the selected backend adapter.
+  # Even the lightweight direct path can benefit from resumable state during interactive use.
+  # Available `kind` options in this harness: `FileCheckpointer`, `MemorySaver`, `SqliteSaver`.
+  # `path` is only used by `FileCheckpointer` and `SqliteSaver`; omit it for `MemorySaver`.
+  checkpointer:
+    ref: checkpointer/sqlite
+  # Upstream execution feature: LangGraph store available to middleware and runtime context hooks.
+  # The default direct host keeps this enabled so middleware can use the same durable store surface as other hosts.
+  store:
+    ref: store/default
+  # Upstream execution feature: no declarative HITL tool routing by default.
+  interruptOn: {}
+  # Upstream execution feature: filesystem middleware settings for LangChain v1 agents.
+  # This only becomes active when `middleware` includes `{ kind: filesystem }`, or when
+  # automatic upstream middleware such as skills or memory need a filesystem backend.
+  # Keep the default root inside the workspace so file-aware middleware stays bounded.
+  filesystem:
+    rootDir: .
+    virtualMode: true
+    maxFileSizeMb: 10
+  # Upstream execution feature: no extra declarative middleware beyond the runtime's automatic injections.
+  # Common upstream middleware kinds that this harness can compile directly from YAML:
+  # - `filesystem`
+  # - `patchToolCalls`
+  # - `summarization`
+  # - `dynamicSystemPrompt`
+  # - `humanInTheLoop`
+  # - `todoList`
+  # - `pii`, `piiRedaction`
+  #
+  # Keep the default empty so the lightweight direct host stays minimal.
+  middleware: []
+  # Upstream execution feature: system prompt for the lightweight direct-response host.
+  # This prompt should keep the agent focused on:
+  # - answering simple requests in one turn
+  # - staying lightweight instead of planning or orchestrating
+  # - avoiding delegation-heavy decomposition unless the caller explicitly switches agents
+  #
+  # The direct host is intentionally narrower than the orchestra host:
+  # - `direct` is optimized for latency and straightforward completion
+  # - `orchestra` is optimized for multi-step work, tools, and delegation
+  #
+  # Keep this prompt biased toward concise, self-contained answers. If richer routing policy is
+  # needed for choosing between host agents, configure that separately via `Runtime.spec.routing`
+  # rather than overloading the direct host prompt with classifier behavior.
+  systemPrompt: |-
+    You are the direct agent.
 
-      This is a manual low-latency host.
-      Answer simple requests directly.
-      Keep the path lightweight.
-      Do not delegate.
-      Do not perform broad multi-step execution.
-      Do not behave like the default execution host.
+    This is a manual low-latency host.
+    Answer simple requests directly.
+    Keep the path lightweight.
+    Do not delegate.
+    Do not perform broad multi-step execution.
+    Do not behave like the default execution host.