Skip to content

docs(architecture): audit Tools and capabilities group against implementation #4799

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Astro-Han merged 5 commits into from
Sep 7, 2026
Merged

docs(architecture): audit Tools and capabilities group against implementation #4799

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c2d3697
docs(architecture): audit Tools and capabilities group against implem…
ggbdpq Sep 4, 2026
c766505
Merge branch 'main' into docs/audit-tools-a4
ggbdpq Sep 5, 2026
2f25ebf
docs: state the current Eval no-web contract in the search capability…
ggbdpq Sep 5, 2026
0c1f521
Merge remote-tracking branch 'upstream/main' into docs/audit-tools-a4
ggbdpq Sep 7, 2026
57b4427
docs(mcp): add LOGNAME to the audited stdio environment allowlist
ggbdpq Sep 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion docs/architecture/mcp-runtime-architecture-draft.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
---
doc_id: architecture.mcp-runtime-architecture-draft
title: "Maka MCP runtime architecture"
language: zh-CN
source_language: zh-CN
implementation_status: current
document_status: current
translation_status: source-only
last_verified: 2026-09-04
Comment thread
Astro-Han marked this conversation as resolved.
owners:
- maka-backend
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
Expand Down Expand Up @@ -113,7 +125,7 @@ Bundled catalog 不是第二份 runtime truth：点击安装只把选中的模

## 5. 安全与权限

- stdio 默认只继承运行所需 allowlist：`PATH`、`HOME`、`USER`、`SHELL`、`LANG`、`LC_*`、`TMPDIR`、`XDG_*` 和 Windows system variables。配置中的显式 `env` 最后覆盖。
- stdio 默认只继承运行所需 allowlist：`PATH`、`HOME`、`USER`、`LOGNAME`、`SHELL`、`LANG`、`LC_*`、`TMPDIR`、`XDG_*` 和 Windows system variables。配置中的显式 `env` 最后覆盖。
- 普通配置型 MCP tool 默认为 `categoryHint: network_send`，用于 trace 分类和 Plan-mode exclusion；它本身不是用户审批机制。`readOnlyHint` 是不可信的 server advisory，不能降低这个分类。受信任的 host composition 可以显式选择更严格的 category/recovery policy，但该 authority 来自 Maka composition，而不是 server annotation。
- Direct/Code Mode 的 managed execution 在 provider dispatch 前由 runtime adapter 检查 `ExecutionBoundary`；network 尚未启用时必须先通过 `requestSandboxBoundary`。协议协商只改变 manager 内部 wire codec，不能绕过这条授权路径。
- manager 只提供 generation-bound tool snapshot 和远端调用。ToolRuntime 总是在 implementation 前投影 `tool_call` / `tool_start`；只有 host 配置 `runtimeCommitSink` 时，才要求 durable T1 在 provider side effect 前成功，并在结果后写 T2。没有 sink 的路径不得声称拥有 durable operation id 或 T1/T2 recovery authority。
Expand Down
12 changes: 12 additions & 0 deletions docs/skill-catalog-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
---
doc_id: skill-catalog-policy
title: "Skill catalog policy"
language: en
source_language: en
implementation_status: current
document_status: current
translation_status: source-only
last_verified: 2026-09-04
owners:
- maka-backend
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
Expand Down
30 changes: 24 additions & 6 deletions docs/web-search-provider-capability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
---
doc_id: web-search-provider-capability
title: "Provider-hosted web search capability"
language: en
source_language: en
implementation_status: current
document_status: current
translation_status: source-only
last_verified: 2026-09-04
owners:
- maka-backend
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
Expand Down Expand Up @@ -71,13 +83,19 @@ All production `AiSdkBackend` composition roots use the same
| Desktop | persisted `webSearch.enabled/defaultProvider` settings | May add provider-native `WebSearch` |
| CLI / TUI / `maka run` | the same persisted settings | May add provider-native `WebSearch` |
| Runtime Host | runtime-policy web-search settings | May add provider-native `WebSearch` |
| Headless Harbor | explicit `MAKA_WEB_SEARCH_ENABLED=true` | May add provider-native `WebSearch` |

Headless remains opt-in because silently enabling network search would change
benchmark semantics and historical baselines. Merely speaking Anthropic
Messages is not enough to infer hosted-search support; Maka uses explicit model
metadata or narrow model-id rules, including DeepSeek V4 Flash on an
`anthropic-compatible` connection.
The former Headless Harbor surface was retired by #2605 (2026-08-11, replaced
by the minimal Eval kernel); its `MAKA_WEB_SEARCH_ENABLED=true` opt-in no
longer exists. Its opt-in rationale — silently enabling network search would
change benchmark semantics and historical baselines — now applies to eval
subjects inverted: current benchmark subjects have no enablement path at all.
Every subject removes `WebSearch`, `WebFetch`, and `FetchURL` from the
provider-visible tool list, and the Eval metering proxy structurally strips
named and provider-native web tools from external-harness requests, so
results stay comparable across providers and baselines. Merely speaking
Anthropic Messages is not enough to infer hosted-search support; Maka uses
explicit model metadata or narrow model-id rules, including DeepSeek V4 Flash
on an `anthropic-compatible` connection.

An explicit `BackendFactoryContext.tools` list is a hard ceiling. Root surfaces
may add native search, but scoped child agents do not gain it unless their
Expand Down