Clarity Runtime

A unified MCP control plane for local and remote services.

______________________________________________________________________

Clarity Runtime是一个轻量级的运行时+网关，用于从一个地方运行、注册和操作MCP服务。

它旨在与Clarity编译器工作流配对，因此服务入职可以成为一个命令：

clarityc start server.clarity

______________________________________________________________________

为什么选择Clarity Runtime？

MCP操作通常是分散的：

• 每个客户端都需要单独的MCP接线
• 本地和远程服务器的管理方式不同
• 运行状况、日志和界面可见性没有共享的状态表

Clarity Runtime将其集中到一个控制平面守护进程中(clarityd)以及一个操作员CLI(clarityctl).

这给了你什么

• 代理客户端的单一网关端点
• 确定性服务标识（无需手动命名）
• 持久服务注册表和生命周期管理
• 每个服务的界面快照（工具/资源/提示）
• 操作和调试状态页面
• Codex和Claude的一次性客户端引导钩子

______________________________________________________________________

建筑

               +----------------------+
               |     clarityctl       |
               | add/start/stop/etc.  |
               +----------+-----------+
                          |
                          v
+-------------------------+--------------------------+
|                     clarityd                       |
|  registry | lifecycle supervisor | interface cache |
+-------------------------+--------------------------+
                          |
                  +-------+--------+
                  |   MCP Gateway  |
                  +-------+--------+
                          |
           +--------------+--------------+
           |                             |
           v                             v
   Local Clarity MCPs             Remote MCP Services
   (compiled to WASM)             (HTTP transports)

______________________________________________________________________

安装+启动

# 1) Install and build once
npm install
npm run build

# 2) Start the runtime
npx clarityd

# Optional: require auth token for all API/MCP calls
# export CLARITYD_AUTH_TOKEN=your-token
# npx clarityd --auth-token your-token

# 3) Add a local service from source (mcp1 -> ./mcp1.clarity)
npx clarityctl add mcp1

# Optional: add all .clarity services in a folder
npx clarityctl add-all ./examples --recursive

# 4) Inspect + wire clients once
npx clarityctl list
npx clarityctl bootstrap --clients codex,claude --transport http --endpoint http://localhost:4707/mcp --update-agents-md

打开控制层： http://localhost:4707/status

默认情况下，Bootstrap不是自动的。跑 clarityctl bootstrap --clients codex,claude --transport http --endpoint http://localhost:4707/mcp 一次（或保持 stdio 如果您更喜欢进程管理桥模式），或使用状态页面“客户端引导配置”部分配置和验证路径。添加 --update-agents-md 还可以在工作区中打乱幂等的受管Clarity默认块 AGENTS.md.

clarityctl add 编译 .clarity 到 .clarity/build/.wasm，然后注册并启动它。

对于本地开发（没有构建工件），您仍然可以使用：

npm run dev:daemon
npm run dev:ctl -- list

启用身份验证后，传递 --auth-token 到 clarityctl （或设置 CLARITYD_AUTH_TOKEN/CLARITY_API_TOKEN 在环境中）。

______________________________________________________________________

命令行界面

clarityctl add 
clarityctl add-all [dir] [--recursive]
clarityctl add-remote --endpoint  --module  [--transport streamable_http|sse_http] [--auth-ref ] [--timeout-ms ] [--allow-tools ] [--max-payload-bytes ] [--max-concurrency ]
clarityctl list
clarityctl status
clarityctl start 
clarityctl stop 
clarityctl restart 
clarityctl introspect 
clarityctl remove  [--cleanup-artifacts]
clarityctl details  [--log-limit ] [--event-limit ] [--call-limit ]
clarityctl logs 
clarityctl auth providers
clarityctl auth validate 
clarityctl auth list-secrets
clarityctl auth set-secret  
clarityctl auth delete-secret 
clarityctl bootstrap --clients codex,claude [--transport stdio|http] [--endpoint ] [--update-agents-md]
clarityctl bootstrap-remove --clients codex,claude
clarityctl doctor

clarityctl doctor 现在验证守护进程连接、编译器可用性和本地构建工作区就绪性。

质量命令：

npm run lint
npm run format
npm run test
npm run test:coverage

______________________________________________________________________

当前状态

针对v0.9基线实施：

• 服务契约和清单模式(clarity.runtime/v1)
• 持久注册表(.clarity/runtime/registry.json)
• 后台程序HTTP API和状态页
• 添加/列出/启动/停止/重新启动/内省/删除流
• 网关 /mcp JSON-RPC端点(initialize, ping, tools/list, tools/call, resources/list, prompts/list)
• 内置运行时控制MCP工具(runtime__status_summary, runtime__list_services, runtime__get_service, runtime__get_logs, runtime__start_service, runtime__stop_service, runtime__restart_service, runtime__refresh_interface, runtime__unquarantine_service, runtime__remove_service, runtime__get_audit, runtime__get_agent_runs, runtime__get_agent_events, runtime__validate_auth_ref, runtime__auth_provider_health, runtime__list_auth_secrets, runtime__set_auth_secret, runtime__delete_auth_secret)
• 内置的Clarity辅助MCP工具(clarity__help, clarity__sources, clarity__project_structure, clarity__ensure_compiler, clarity__bootstrap_app)用于默认语言指导、源代码发现、应用程序脚手架、编译器准备/安装检查和一次调用引导
• 门控MCP自我配置工具(runtime__register_local, runtime__register_remote, runtime__register_via_url, runtime__apply_manifest)受到保护 CLARITY_ENABLE_MCP_PROVISIONING=1
• stdio桥接模式 clarityctl gateway serve --stdio
• 编译器通过以下方式辅助入职 clarityctl add （编译+注册+启动+反思）
• 本地服务的本地函数执行工具(__fn__)
• 基线远程策略控制（超时+允许的工具+有效负载大小+并发清单策略+可选主机分配列表）
• Codex/Claude配置文件的引导编写程序
• 持久运行时遥测存储(.clarity/runtime/telemetry.json)用于跨守护进程重启的事件+服务日志
• 代理编排可观察性(agent.* 事件， /api/agents/* API、UI Agents 选项卡）
• 脱视觉端点/工具，可选本地工件清理
• 端到端运行时集成测试，涵盖API/MCP注册/调用/移除生命周期

尚未实施：

• 远程身份验证/策略隔离强化，以实现更严格的多租户信任边界
• 运行时TypeScript聊天执行器桥的原生Clarity编排替换(RUNTIME-HITL-CLARITY-001)

______________________________________________________________________

路线图

• \[x\] 运行时编译器路径(clarityctl add )
• \[\]本机编译器命令(clarityc start )in LLM-lang
• \[x\] 添加策略引擎基线（超时、分配列表、并发性、有效负载限制）
• \[\]完成远程身份验证/策略隔离强化（提供程序后端+验证+文件秘密生命周期着陆）
• \[x\] 添加MCP自我配置工具（LLM可以通过MCP注册/安装服务，并获得批准+策略门）
• \[x\] 添加隔离/恢复和更丰富的健康诊断
• \[x\] 添加界面差异和审计/事件时间线
• \[x\] 添加代理可观察性（运行摘要+时间线+UI选项卡拆分）

进度快照

______________________________________________________________________

规格

• 运行时规范： docs/spec/v1/runtime-spec.md
• 清单架构： schemas/mcp-service-v1.schema.json
• 分层要求： docs/requirements/layered-runtime-requirements.md
• 共享语言要求摄入： ../LLM-lang/docs/runtime-cli-language-requirements.md
• v0.9路线图： docs/roadmap/v0.9-roadmap.md

远程策略旋钮

• add-remote --timeout-ms ：设置每个服务的远程请求超时。
• add-remote --transport ：选择远程MCP传输，无需手动编辑清单。
• add-remote --allow-tools ：限制可调用的远程工具。
• add-remote --max-payload-bytes ：设置每个远程服务的最大请求/响应有效负载字节数。
• add-remote --max-concurrency ：设置每个服务的最大并发飞行中远程请求数。
• add-remote --auth-ref ：远程身份验证引用（支持 legacy-name, env:ENV_VAR, file:relative/path, header_env:Header-Name:ENV_VAR).
• CLARITY_REMOTE_ALLOWED_HOSTS=host1,host2：可选的全局远程主机分配列表。
• CLARITY_REMOTE_DEFAULT_TIMEOUT_MS=20000：未设置清单超时时的默认超时。
• CLARITY_REMOTE_MAX_PAYLOAD_BYTES=1048576：未设置清单值时的默认最大请求/响应有效负载字节数。
• CLARITY_REMOTE_MAX_CONCURRENCY=8：未设置清单值时，每个服务的默认最大运行中远程请求数。
• CLARITY_REMOTE_AUTH_FILE_ROOT=/absolute/path：可选的根目录 file: auth-refs（默认为 .clarity/secrets 在工作空间下）。
• CLARITY_ENABLE_MCP_PROVISIONING=1：启用运行时MCP自我配置工具(runtime__register_*, runtime__apply_manifest).
• CLARITY_ENABLE_COMPILER_INSTALL=1：允许 clarity__ensure_compiler 执行安装命令。
• CLARITY_COMPILER_INSTALL_ALLOWLIST=brew,apt-get：可选的安装程序命令allowlist clarity__ensure_compiler.
• CLARITY_AUDIT_INCLUDE_LIFECYCLE=1：在审核中包括服务生命周期事件(service.*).集 0 仅记录MCP工具调用。
• CLARITY_A2A_MAX_MESSAGE_BYTES=65536：正式摄入A2A包膜的最大可接受体型 POST /api/a2a/messages.
• 运行时聊天调度：

- CLARITY_HITL_CHAT_MODE=auto|echo|disabled （全局默认） - 清单中的每个代理覆盖： metadata.agent.chat (mode, handlerTool, historyEnabled, historyMaxTurns, historyMaxChars) - 本地wasm-env/秘密注射： spec.origin.env[] 随着 value 或 secretRef （仅按服务执行上下文解析） - 本地运行时聊天模型密钥覆盖： metadata.agent.chat.apiKeyEnv 因当地垃圾而受到表彰 call_model / call_model_system - 显式直接HITL能力： metadata.agent.hitl=true - 在 auto 模式运行时分派给代理拥有的处理程序工具（本地默认值 fn__receive_chat，远程默认 receive_chat) - 运行时间总是过去的 contextVersion="context.v1" 和 context 聊天处理程序 - 提供者密钥/模型应由代理实现拥有，而不是运行时拥有

• 定时器时间表：

- 声明 metadata.agent.timer.schedules[] (scheduleId, scheduleExpr 随着 every ) - 运行时发出规范定时器触发上下文(scheduleId, scheduleExpr, firedAt)并在服务运行时执行计时器运行

安全默认值

• 如果 CLARITYD_AUTH_TOKEN 设置后，受保护的控制端点需要通过以下方式获取令牌 Authorization: Bearer 或 x-clarity-token.
• 如果没有设置令牌，则运行时API仅限于环回调用者。
• 查询令牌身份验证(?token=)仅限于本地环回SSE端点(/events, /api/events)对于浏览器 EventSource 只有兼容性。
• 状态UI仍然可以通过打开 ?token=；该页将令牌存储在本地存储中，将其从URL中删除，并对API调用使用头验证。

审计和事件

• GET /api/audit?limit=200：最新运行时审计/事件。
• GET /api/agents/registry：注册的代理服务和声明的功能。
• GET /api/agents/runs?limit=100：代理运行摘要。
• GET /api/agents/events?limit=200：最近的代理时间线事件。
• GET /api/agents/runs/:runId/events?limit=200：一次运行代理时间线。
• GET /api/a2a/capabilities：列出启用A2A的代理和协议配置文件。
• POST /api/a2a/messages：摄入一个正式的A2A信封(clarity.a2a.v1)并标准化为规范 agent.* 事件。
• POST /api/agents/events：摄入一个 agent.* 编排事件。
• GET /api/events：实时运行时事件的SSE流。
• 状态页面现在包括单独的 MCP 和 Agents 选项卡。
• 遥测在守护进程重新启动后持续存在 .clarity/runtime/telemetry.json.
• 审计策略始终记录MCP工具调用(mcp.tool_called)，不包括秘密有效载荷，可以包括生命周期事件(service.*)via CLARITY_AUDIT_INCLUDE_LIFECYCLE=1 （默认启用）。
• 身份验证生命周期/验证API：

- GET /api/security/auth/providers - GET|POST /api/security/auth/validate - GET /api/security/auth/secrets - POST /api/security/auth/secrets （要求 CLARITY_ENABLE_MCP_PROVISIONING=1) - DELETE /api/security/auth/secrets （要求 CLARITY_ENABLE_MCP_PROVISIONING=1)

• 服务取消设置API：
• DELETE /api/services/:serviceId 带可选车身 { "cleanup_artifacts": true }

许可证

• 存储库许可证：MIT（参见 LICENSE).
• 运行时分布式工件必须保留存储库许可证文本并声明与SPDX兼容的元数据(MIT)发布时在包/构建元数据中。

CI/CD和GitHub

• 公关CI： .github/workflows/build.yml （分支命名+构建+lint+格式+测试）。
• 每次合并/推送时进行快照打包 main: .github/workflows/snapshot.yml （包括覆盖门和上传快照工件）。
• 标记为发布管道： .github/workflows/release.yml （构建、测试、覆盖率、打包、校验和、GitHub Release资产）。
• 自动版本控制/变更日志PR： .github/workflows/release-please.yml (.release-please-*.json config）。
• 安全门：

- .github/workflows/dependency-review.yml - .github/workflows/codeql.yml - .github/workflows/secret-scan.yml

• 回购自动化：

- Dependabot： .github/dependabot.yml - 代码所有者： .github/CODEOWNERS - PR/问题模板： .github/pull_request_template.md, .github/ISSUE_TEMPLATE/* - 标签同步+路径标签： .github/workflows/labels-sync.yml, .github/workflows/labeler.yml, .github/labeler.yml - 可选项目自动添加： .github/workflows/project-automation.yml （套 GH_PROJECT_URL 变量和 ADD_TO_PROJECT_PAT 秘密）

所需GitHub设置（手动）

• 保护 main:

- 合并前需要拉取请求 - 合并前需要通过状态检查 - 要求分支机构在合并前保持最新状态 - 需要线性历史记录

• 合并策略：

- 启用壁球合并 - 禁用合并提交

• 可选硬化：

- 限制谁可以推送 main - 需要代码所有者的审查

您可以将基线分支保护策略应用于：

./scripts/github/apply-branch-protection.sh  

承诺/释放公约

• 使用传统的提交前缀，这样发布自动化就可以推断出版本差异：

- feat: ... - fix: ... - chore: ... - docs: ... - refactor: ...

• 使用 BREAKING CHANGE: 在提交重大颠簸的尸体中。

贡献

此仓库使用基于中继的开发：

1. 保持 main 随时可发布。
2. 分支机构从 main，保持分支短命，并迅速合并回来。
3. 按预期结果（而非实施细节）命名每个分支：

- result/ - hotfix/ - codex/ - （自动化例外） dependabot/*

1. 打开PR main 带有行为/基本原理注释。
2. 确保CI为绿色(.github/workflows/build.yml：分支名称检查+构建+lint+格式+测试）。

对于较大的架构更改，请先打开一个问题，以便在控制平面契约上对齐。