Skip to content

feat(runtime): defer non-direct tools by default - #4098

Merged
Astro-Han merged 1 commit into
mainfrom
feat/4091-defer-low-frequency-tools
Aug 28, 2026
Merged

feat(runtime): defer non-direct tools by default#4098
Astro-Han merged 1 commit into
mainfrom
feat/4091-defer-low-frequency-tools

Conversation

@Astro-Han

@Astro-Han Astro-Han commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Make the final executable tool binding the only authority for availability.
  • On ordinary Runtime Host runs, defer every bound tool outside the fixed direct baseline behind tool_search; an ungrouped future tool therefore becomes deferred automatically.
  • Keep Skill, SkillSearch, and provider-routed apply_patch direct. Preserve the existing requiredToolNames turn-scoped orchestration promotion without adding new state-driven rules.
  • Treat Client Capability groups only as optional search labels and descriptions. They no longer decide whether a tool is deferred.
  • Keep explicit boundTools and toolProfile ceilings fully visible by omitting search availability, preserving their exact step-0 wire schema.
  • Remove the shared static tool catalog, the Runtime Host catalog projection, its derivation tests and exports, and the Runtime memory-group special case. The change is 244 additions and 708 deletions relative to current main.

Closes #4091.

Compatibility retained

  • Historical load_tools transcript rendering remains readable, but no new turn uses it for activation.
  • Historical economy telemetry remains readable. New diagnostics continue to use search.
  • Client Capability group metadata remains supported because it adds dynamic provider-owned search context without becoming another availability authority.

Testing

  • npm --workspace @maka/core run build
  • npm --workspace @maka/runtime run build
  • npm --workspace @maka/runtime-host run build
  • npm --workspace @maka/core run typecheck
  • npm --workspace @maka/runtime run typecheck
  • npm --workspace @maka/runtime-host run typecheck
  • npm run format:check
  • Focused Runtime availability/backend/wire/capacity suites: 409 tests passed
  • Focused Runtime Host composition and Client Capability suites: 52 tests passed
  • git diff --check

AI assistance disclosure

Codex implemented the change, simplified the architecture, migrated the tests, and ran the validation above. The human contributor must review the final diff and owns the decision to submit and merge it.

Generated-by: Codex

@github-actions github-actions Bot added the effort/M Under 500 readable lines label Aug 28, 2026
@Astro-Han
Astro-Han marked this pull request as ready for review August 28, 2026 15:56

@M4n5ter M4n5ter left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE — I found no P0–P3 issues on exact head f10b9d7130c85457918261ba382c99f7db79c4a4.

I verified the reachable tool paths, including the normal root turn, Runtime-injected memory tools, OpenAI Responses aliasing, exact boundTools and toolProfile ceilings, required orchestration tools, and attempts to call a deferred tool before searching for it. Deferred tools remain discoverable through tool_search, become available on the following provider step, and cannot silently execute before activation. Exact child/tool-profile ceilings remain exact.

The change reuses the existing catalog and activation authority rather than adding another state machine or execution path. It removes low-frequency schemas from the initial provider request while keeping one catalog source for grouping and discovery.

Verification completed:

  • six package builds and the CLI build;
  • 266 focused tests on the PR head;
  • a synthetic merge with current main, followed by six package builds and 267 focused tests;
  • the complete CLI suite (617 tests), Biome, and git diff --check.

The hosted test check is currently red because an untouched CLI timing test timed out. The same test passed in the complete local CLI suite and in 30 repeated isolated runs, while current main is green. The code review result is APPROVE, but this does not claim that CI is green or that the PR is ready to merge.


Posted by an automated review agent operated by @M4n5ter. This is not an
independent human review and does not satisfy the committer review required by
CONTRIBUTING.md. A human is accountable for this comment — please push back if
anything here is wrong.

简体中文

本条评论由 @M4n5ter 运行的自动化审查程序发出。它不构成 CONTRIBUTING.md
所要求的独立人类审查,也不能替代人类审查。有人类对本条评论负责,如有错误请直接指出。

Make the final executable binding the tool-availability authority.

- defer every bound tool outside the direct baseline when search availability is enabled
- keep explicit bound and profile ceilings fully visible by omitting search availability
- retain Client Capability groups only as optional search metadata
- remove the shared static tool catalog, Host projection, and Runtime memory-group special case
- keep Skill, SkillSearch, and provider-routed apply_patch direct

Closes #4091

Generated-by: Codex
@Astro-Han
Astro-Han force-pushed the feat/4091-defer-low-frequency-tools branch from f10b9d7 to d6d528d Compare August 28, 2026 16:36
@Astro-Han Astro-Han changed the title feat(runtime): defer low-frequency catalog tools behind tool_search feat(runtime): defer non-direct tools by default Aug 28, 2026

@jackwener jackwener left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE — I found no P0–P3 issues on exact head d6d528d3d860d159fdd34e60a9abe19bd904bbf3.

This change makes the final bound tool list the only availability authority. On an ordinary Runtime Host run, every bound tool outside the fixed direct baseline is deferred behind tool_search. Client Capability groups remain labels and search text only; they no longer decide whether a tool is deferred. Explicit boundTools and toolProfile ceilings omit search, so those lists stay fully visible at step 0.

I checked the reachable paths that matter:

  • Default Host composition (no ceiling) supplies a search config even when there are no client groups, so an ungrouped future tool is deferred automatically and listed under other.
  • Skill, SkillSearch, and provider-routed apply_patch stay direct whenever they are bound.
  • Runtime-injected memory tools are deferred and only become callable after a successful tool_search on that turn.
  • Swarm/graph required orchestration tools still become visible for the current turn without changing the activation map.
  • A same-step call to a deferred tool is still refused at the execute boundary; it becomes callable on the following provider step after search.
  • Child and profile ceilings omit search and keep the exact bound schema.
  • The static product catalog, Host projection, and leftover package exports are gone.

I did not treat issue #4091 as evidence. The Host production composition test is enough to falsify the old default: step 0 now advertises the direct baseline plus tool_search, not the previous ~30-tool surface.

I am not merging this. It is a feature; merge is a human call. Hosted test, audit, and ubuntu-latest were still queued when I posted. This review does not claim CI is green.


Posted by an automated review agent operated by @WAWQAQ. This is not an
independent human review and does not satisfy the committer review required by
CONTRIBUTING.md. A human is accountable for this comment — please push back if
anything here is wrong.

简体中文

APPROVE — 精确 head d6d528d3d860d159fdd34e60a9abe19bd904bbf3 上我没有发现 P0–P3。

这次改动让最终绑定的工具列表成为可用性的唯一依据。普通 Runtime Host 会话里,固定直接基线之外的绑定工具都默认藏到 tool_search 后面。Client Capability 分组只还做搜索标签,不再决定工具是否延迟加载。明确的 boundTools / toolProfile 上限会省略搜索,所以这些列表在第 0 步仍然完整可见。

我核对过会走到的路径:默认 Host 组合即使没有客户端分组也会打开搜索;Skill / SkillSearch / apply_patch 保持直接可见;Runtime 注入的 memory 工具要先搜索才能调用;swarm/graph 的必选编排工具仍会在当轮直接露出;延迟工具在同一步调用会被拒绝;子代理和 profile 上限保持精确可见;静态 catalog 和 Host 投影已经删干净。

我没有把 issue #4091 当证据。Host 生产组合测试已经能证伪旧默认:第 0 步现在只有直接基线加上 tool_search,不再是大约 30 个工具。

这是功能变更,我不合入,合入由人类决定。发这条时 hosted test / audit / ubuntu-latest 仍在排队。这次审查不表示 CI 已绿。

本条评论由 @WAWQAQ 运行的自动化审查程序发出。它不构成 CONTRIBUTING.md
所要求的独立人类审查,也不能替代人类审查。有人类对本条评论负责,如有错误请直接指出。

@Astro-Han
Astro-Han merged commit 4e85f51 into main Aug 28, 2026
6 checks passed
@Astro-Han
Astro-Han deleted the feat/4091-defer-low-frequency-tools branch August 28, 2026 17:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/M Under 500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(runtime): defer low-frequency catalog tools behind tool_search

3 participants