{"id":45374944,"url":"https://github.com/clarity-llm-lang/clarity-runtime","last_synced_at":"2026-03-05T09:07:06.977Z","repository":{"id":339667379,"uuid":"1162886372","full_name":"clarity-llm-lang/clarity-runtime","owner":"clarity-llm-lang","description":"Local control-plane runtime for managing local and remote MCP services from a single gateway","archived":false,"fork":false,"pushed_at":"2026-03-04T11:38:37.000Z","size":804,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T12:52:05.224Z","etag":null,"topics":["ai-tooling","clarity","control-plane","mcp","runtime"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clarity-llm-lang.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":"docs/roadmap/v0.9-roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-20T20:22:44.000Z","updated_at":"2026-03-04T11:26:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/clarity-llm-lang/clarity-runtime","commit_stats":null,"previous_names":["clarity-llm-lang/clarity-runtime"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/clarity-llm-lang/clarity-runtime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarity-llm-lang%2Fclarity-runtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarity-llm-lang%2Fclarity-runtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarity-llm-lang%2Fclarity-runtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarity-llm-lang%2Fclarity-runtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clarity-llm-lang","download_url":"https://codeload.github.com/clarity-llm-lang/clarity-runtime/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarity-llm-lang%2Fclarity-runtime/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30117516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T08:19:04.902Z","status":"ssl_error","status_checked_at":"2026-03-05T08:17:37.148Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tooling","clarity","control-plane","mcp","runtime"],"created_at":"2026-02-21T16:06:29.815Z","updated_at":"2026-03-05T09:07:06.955Z","avatar_url":"https://github.com/clarity-llm-lang.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/clarity-runtime-banner.svg\" alt=\"Clarity Runtime\" width=\"860\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA unified MCP control plane for local and remote services.\u003c/strong\u003e\n\u003c/p\u003e\n\n---\n\nClarity Runtime is a lightweight runtime + gateway for running, registering, and operating MCP services from one place.\n\nIt is designed to pair with Clarity compiler workflows so service onboarding can become one command:\n\n```bash\nclarityc start server.clarity\n```\n\n---\n\n## Why Clarity Runtime?\n\nMCP operations are usually fragmented:\n\n- every client needs separate MCP wiring\n- local and remote servers are managed differently\n- there is no shared status surface for health, logs, and interface visibility\n\nClarity Runtime centralizes this into one control plane daemon (`clarityd`) and one operator CLI (`clarityctl`).\n\n### What this gives you\n\n- Single gateway endpoint for agent clients\n- Deterministic service identity (no required manual naming)\n- Persistent service registry and lifecycle management\n- Interface snapshots (tools/resources/prompts) per service\n- Status page for operations and debugging\n- One-time client bootstrap hooks for Codex and Claude\n\n---\n\n## Architecture\n\n```text\n               +----------------------+\n               |     clarityctl       |\n               | add/start/stop/etc.  |\n               +----------+-----------+\n                          |\n                          v\n+-------------------------+--------------------------+\n|                     clarityd                       |\n|  registry | lifecycle supervisor | interface cache |\n+-------------------------+--------------------------+\n                          |\n                  +-------+--------+\n                  |   MCP Gateway  |\n                  +-------+--------+\n                          |\n           +--------------+--------------+\n           |                             |\n           v                             v\n   Local Clarity MCPs             Remote MCP Services\n   (compiled to WASM)             (HTTP transports)\n```\n\n---\n\n## Install + Start\n\n```bash\n# 1) Install and build once\nnpm install\nnpm run build\n\n# 2) Start the runtime\nnpx clarityd\n\n# Optional: require auth token for all API/MCP calls\n# export CLARITYD_AUTH_TOKEN=your-token\n# npx clarityd --auth-token your-token\n\n# 3) Add a local service from source (mcp1 -\u003e ./mcp1.clarity)\nnpx clarityctl add mcp1\n\n# Optional: add all .clarity services in a folder\nnpx clarityctl add-all ./examples --recursive\n\n# 4) Inspect + wire clients once\nnpx clarityctl list\nnpx clarityctl bootstrap --clients codex,claude --transport http --endpoint http://localhost:4707/mcp --update-agents-md\n```\n\nOpen the control layer: [http://localhost:4707/status](http://localhost:4707/status)\n\nBootstrap is not automatic by default. Run `clarityctl bootstrap --clients codex,claude --transport http --endpoint http://localhost:4707/mcp` once (or keep `stdio` if you prefer process-managed bridge mode), or use the status page \"Client Bootstrap Config\" section to configure and verify paths. Add `--update-agents-md` to also upsert an idempotent managed Clarity-defaults block in workspace `AGENTS.md`.\n\n`clarityctl add \u003cname\u003e` compiles `\u003cname\u003e.clarity` to `.clarity/build/\u003cname\u003e.wasm`, then registers and starts it.\n\nFor local development (without build artifacts), you can still use:\n\n```bash\nnpm run dev:daemon\nnpm run dev:ctl -- list\n```\n\nWhen auth is enabled, pass `--auth-token \u003ctoken\u003e` to `clarityctl` (or set `CLARITYD_AUTH_TOKEN`/`CLARITY_API_TOKEN` in the environment).\n\n---\n\n## CLI\n\n```bash\nclarityctl add \u003cservice_or_source_path\u003e\nclarityctl add-all [dir] [--recursive]\nclarityctl add-remote --endpoint \u003curl\u003e --module \u003cname\u003e [--auth-ref \u003cname\u003e] [--timeout-ms \u003cms\u003e] [--allow-tools \u003ca,b,c\u003e] [--max-payload-bytes \u003cbytes\u003e] [--max-concurrency \u003cn\u003e]\nclarityctl list\nclarityctl status\nclarityctl start \u003cservice_id\u003e\nclarityctl stop \u003cservice_id\u003e\nclarityctl restart \u003cservice_id\u003e\nclarityctl introspect \u003cservice_id\u003e\nclarityctl remove \u003cservice_id\u003e [--cleanup-artifacts]\nclarityctl details \u003cservice_id\u003e [--log-limit \u003cn\u003e] [--event-limit \u003cn\u003e] [--call-limit \u003cn\u003e]\nclarityctl logs \u003cservice_id\u003e\nclarityctl auth providers\nclarityctl auth validate \u003cauth_ref\u003e\nclarityctl auth list-secrets\nclarityctl auth set-secret \u003cauth_ref\u003e \u003csecret\u003e\nclarityctl auth delete-secret \u003cauth_ref\u003e\nclarityctl bootstrap --clients codex,claude [--transport stdio|http] [--endpoint \u003curl\u003e] [--update-agents-md]\nclarityctl bootstrap-remove --clients codex,claude\nclarityctl doctor\n```\n\n`clarityctl doctor` now validates daemon connectivity, compiler availability, and local build workspace readiness.\n\nQuality commands:\n\n```bash\nnpm run lint\nnpm run format\nnpm run test\nnpm run test:coverage\n```\n\nLegacy compatibility commands (still supported):\n\n```bash\nclarityctl add-local --source \u003cfile.clarity\u003e --module \u003cname\u003e --wasm \u003cfile.wasm\u003e\nclarityctl start-source --source \u003cfile.clarity\u003e [--module \u003cname\u003e] [--wasm \u003cfile.wasm\u003e]\n```\n\n---\n\n## Current Status\n\nImplemented for v0.9 baseline:\n\n- service contracts and manifest schema (`clarity.runtime/v1`)\n- persistent registry (`.clarity/runtime/registry.json`)\n- daemon HTTP API and status page\n- add/list/start/stop/restart/introspect/remove flows\n- gateway `/mcp` JSON-RPC endpoint (`initialize`, `ping`, `tools/list`, `tools/call`, `resources/list`, `prompts/list`)\n- built-in runtime control MCP tools (`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`)\n- built-in Clarity-assist MCP tools (`clarity__help`, `clarity__sources`, `clarity__project_structure`, `clarity__ensure_compiler`, `clarity__bootstrap_app`) for default-language guidance, source discovery, app scaffolding, compiler readiness/install checks, and one-call bootstrap\n- gated MCP self-provisioning tools (`runtime__register_local`, `runtime__register_remote`, `runtime__register_via_url`, `runtime__apply_manifest`) protected by `CLARITY_ENABLE_MCP_PROVISIONING=1`\n- stdio bridge mode via `clarityctl gateway serve --stdio`\n- compiler-assisted onboarding via `clarityctl add \u003cservice\u003e` (compile + register + start + introspect)\n- local function execution tools for local services (`\u003cnamespace\u003e__fn__\u003cexported_function\u003e`)\n- baseline remote policy controls (timeout + allowed-tools + payload-size + concurrency manifest policy + optional host allowlist)\n- bootstrap writers for Codex/Claude config files\n- durable runtime telemetry store (`.clarity/runtime/telemetry.json`) for events + service logs across daemon restarts\n- agent orchestration observability (`agent.*` events, `/api/agents/*` APIs, UI `Agents` tab)\n- deprovision endpoint/tooling with optional local artifact cleanup\n- end-to-end runtime integration tests covering API/MCP registration/call/remove lifecycle\n\nNot implemented yet:\n\n- remote auth/policy isolation hardening for stricter multi-tenant trust boundaries\n- language-level A2A effect/module integration (`std/a2a`) emitting runtime orchestration events by default\n\n---\n\n## Roadmap\n\n- [x] Runtime-side compiler path (`clarityctl add \u003cservice\u003e`)\n- [ ] Native compiler command (`clarityc start \u003cfile.clarity\u003e`) in `LLM-lang`\n- [x] Add policy engine baseline (timeouts, allowlists, concurrency, payload limits)\n- [ ] Complete remote auth/policy isolation hardening (provider backend + validation + file-secret lifecycle landed)\n- [x] Add MCP self-provisioning tools (LLM can register/install services via MCP with approval + policy gates)\n- [x] Add quarantine/recovery and richer health diagnostics\n- [x] Add interface diffing and audit/event timeline\n- [x] Add agent observability (run summaries + timeline + UI tab split)\n\n## Progress Snapshot\n\n| Area                           | Status          | Notes                                                                                                                                                                                                                               |\n| ------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Registry + lifecycle           | Done            | Persistent service records, start/stop/restart, health state                                                                                                                                                                        |\n| Gateway MCP transport          | Done            | `/mcp` JSON-RPC with list/call routing                                                                                                                                                                                              |\n| Runtime as MCP control plane   | Done            | `runtime__*` tools for status, service ops, logs, audit, quarantine recovery                                                                                                                                                        |\n| Stdio gateway bridge           | Done            | `clarityctl gateway serve --stdio` forwards to daemon gateway                                                                                                                                                                       |\n| Remote MCP proxying            | Done (baseline) | Initialize/introspect/tool forwarding                                                                                                                                                                                               |\n| Compiler-driven onboarding     | In progress     | Runtime side done; `clarityc start` exists in `LLM-lang` and delegates to `clarityctl add`; keep cross-repo contract/version alignment                                                                                              |\n| Local function execution       | Done (baseline) | `\u003cnamespace\u003e__fn__*` tools discovered from wasm exports and executed via compiler runtime                                                                                                                                           |\n| In-process WASM host execution | Done            | Local function tools execute directly via wasm instantiate/call in runtime                                                                                                                                                          |\n| Auth/policy hardening          | In progress     | Timeout/allowed-tools/payload-size/concurrency/host-allowlist baseline implemented; auth provider backend (`legacy env`, `env`, `file`, `header_env`) + validation/secret lifecycle tools added; isolation policy hardening pending |\n| MCP self-provisioning          | Done (gated)    | `runtime__register_local`, `runtime__register_remote`, `runtime__apply_manifest` behind `CLARITY_ENABLE_MCP_PROVISIONING=1`                                                                                                         |\n| Durable audit/log persistence  | Done            | Events + service logs persisted to `.clarity/runtime/telemetry.json` and reloaded on daemon boot                                                                                                                                    |\n| Agent observability            | Done (baseline) | `agent.*` event persistence, `/api/agents/*` APIs, and status UI `Agents` tab for run/timeline visibility                                                                                                                           |\n| Deprovision + cleanup          | Done            | `DELETE /api/services/:id` and `clarityctl remove` with optional local artifact cleanup                                                                                                                                             |\n| Runtime integration tests      | Done (baseline) | End-to-end API/MCP tests for register/start/introspect/call/remove                                                                                                                                                                  |\n\n---\n\n## Spec\n\n- Runtime spec: `docs/spec/v1/runtime-spec.md`\n- Manifest schema: `schemas/mcp-service-v1.schema.json`\n- Layered requirements: `docs/requirements/layered-runtime-requirements.md`\n- v0.9 roadmap: `docs/roadmap/v0.9-roadmap.md`\n\n## Remote Policy Knobs\n\n- `add-remote --timeout-ms \u003cms\u003e`: set per-service remote request timeout.\n- `add-remote --allow-tools \u003ctool_a,tool_b\u003e`: restrict callable remote tools.\n- `add-remote --max-payload-bytes \u003cbytes\u003e`: set max request/response payload bytes per remote service.\n- `add-remote --max-concurrency \u003cn\u003e`: set max concurrent in-flight remote requests per service.\n- `add-remote --auth-ref \u003cref\u003e`: remote auth reference (supports `legacy-name`, `env:ENV_VAR`, `file:relative/path`, `header_env:Header-Name:ENV_VAR`).\n- `CLARITY_REMOTE_ALLOWED_HOSTS=host1,host2`: optional global remote host allowlist.\n- `CLARITY_REMOTE_DEFAULT_TIMEOUT_MS=20000`: default timeout when manifest timeout is not set.\n- `CLARITY_REMOTE_MAX_PAYLOAD_BYTES=1048576`: default max request/response payload bytes when manifest value is not set.\n- `CLARITY_REMOTE_MAX_CONCURRENCY=8`: default max in-flight remote requests per service when manifest value is not set.\n- `CLARITY_REMOTE_AUTH_FILE_ROOT=/absolute/path`: optional root directory for `file:` auth refs (defaults to `.clarity/secrets` under workspace).\n- `CLARITY_ENABLE_MCP_PROVISIONING=1`: enable runtime MCP self-provisioning tools (`runtime__register_*`, `runtime__apply_manifest`).\n- `CLARITY_ENABLE_COMPILER_INSTALL=1`: allow `clarity__ensure_compiler` to execute install commands.\n- `CLARITY_COMPILER_INSTALL_ALLOWLIST=brew,apt-get`: optional installer command allowlist for `clarity__ensure_compiler`.\n- `CLARITY_AUDIT_INCLUDE_LIFECYCLE=1`: include service lifecycle events in audit (`service.*`). Set `0` to log only MCP tool calls.\n- `CLARITY_A2A_MAX_MESSAGE_BYTES=65536`: max accepted body size for formal A2A envelope ingestion at `POST /api/a2a/messages`.\n- Runtime chat dispatch:\n  - `CLARITY_HITL_CHAT_MODE=auto|echo|disabled` (global default)\n  - per-agent overrides in manifest: `metadata.agent.chat` (`mode`, `handlerTool`)\n  - in `auto` mode runtime dispatches to agent-owned handler tools (local default `fn__receive_chat`, remote default `receive_chat`)\n  - provider keys/models should be owned by the agent implementation, not runtime\n\n## Security Defaults\n\n- If `CLARITYD_AUTH_TOKEN` is set, all `/api/*` and `/mcp` requests require that token via `Authorization: Bearer \u003ctoken\u003e` or `x-clarity-token`.\n- If no token is set, runtime APIs are limited to loopback callers only.\n- Status UI accepts `?token=\u003ctoken\u003e` for local browser sessions when token auth is enabled.\n\n## Audit And Events\n\n- `GET /api/audit?limit=200`: latest runtime audit/events.\n- `GET /api/agents/registry`: registered agent services and declared capabilities.\n- `GET /api/agents/runs?limit=100`: agent run summaries.\n- `GET /api/agents/events?limit=200`: recent agent timeline events.\n- `GET /api/agents/runs/:runId/events?limit=200`: one-run agent timeline.\n- `GET /api/a2a/capabilities`: list A2A-enabled agents and protocol profile.\n- `POST /api/a2a/messages`: ingest one formal A2A envelope (`clarity.a2a.v1`) and normalize to canonical `agent.*` events.\n- `POST /api/agents/events`: ingest one `agent.*` orchestration event.\n- `GET /api/events`: SSE stream for live runtime events.\n- Status page now includes separate `MCP` and `Agents` tabs.\n- Telemetry persists across daemon restarts in `.clarity/runtime/telemetry.json`.\n- Audit policy always records MCP tool invocations (`mcp.tool_called`), excludes secret payloads, and can include lifecycle events (`service.*`) via `CLARITY_AUDIT_INCLUDE_LIFECYCLE=1` (default on).\n- Auth lifecycle/validation APIs:\n  - `GET /api/security/auth/providers`\n  - `GET|POST /api/security/auth/validate`\n  - `GET /api/security/auth/secrets`\n  - `POST /api/security/auth/secrets` (requires `CLARITY_ENABLE_MCP_PROVISIONING=1`)\n  - `DELETE /api/security/auth/secrets` (requires `CLARITY_ENABLE_MCP_PROVISIONING=1`)\n- Service deprovision API:\n  - `DELETE /api/services/:serviceId` with optional body `{ \"cleanup_artifacts\": true }`\n\n## CI/CD And GitHub\n\n- PR CI: `.github/workflows/build.yml` (branch naming + build + lint + format + test).\n- Snapshot packaging on every merge/push to `main`: `.github/workflows/snapshot.yml` (includes coverage gate and uploads snapshot artifact).\n- Tagged release pipeline: `.github/workflows/release.yml` (build, test, coverage, package, checksums, GitHub Release assets).\n- Automated versioning/changelog PRs: `.github/workflows/release-please.yml` (`.release-please-*.json` config).\n- Security gates:\n  - `.github/workflows/dependency-review.yml`\n  - `.github/workflows/codeql.yml`\n  - `.github/workflows/secret-scan.yml`\n- Repo automation:\n  - Dependabot: `.github/dependabot.yml`\n  - CODEOWNERS: `.github/CODEOWNERS`\n  - PR/Issue templates: `.github/pull_request_template.md`, `.github/ISSUE_TEMPLATE/*`\n  - Label sync + path labeling: `.github/workflows/labels-sync.yml`, `.github/workflows/labeler.yml`, `.github/labeler.yml`\n  - Optional project auto-add: `.github/workflows/project-automation.yml` (set `GH_PROJECT_URL` variable and `ADD_TO_PROJECT_PAT` secret)\n\n### Required GitHub Settings (Manual)\n\n- Protect `main`:\n  - Require pull requests before merge\n  - Require status checks to pass before merge\n  - Require branches to be up to date before merge\n  - Require linear history\n- Merge strategy:\n  - Enable squash merge\n  - Disable merge commits\n- Optional hardening:\n  - Restrict who can push to `main`\n  - Require review from Code Owners\n\nYou can apply a baseline branch-protection policy with:\n\n```bash\n./scripts/github/apply-branch-protection.sh \u003cowner\u003e \u003crepo\u003e\n```\n\n### Commit/Release Convention\n\n- Use conventional commit prefixes so release automation can infer version bumps:\n  - `feat: ...`\n  - `fix: ...`\n  - `chore: ...`\n  - `docs: ...`\n  - `refactor: ...`\n- Use `BREAKING CHANGE:` in commit bodies for major bumps.\n\n## Contributing\n\nThis repo uses trunk-based development:\n\n1. Keep `main` releasable at all times.\n2. Branch from `main`, keep branches short-lived, and merge back quickly.\n3. Name every branch by the expected outcome (not implementation details):\n   - `result/\u003coutcome-kebab-case\u003e`\n   - `hotfix/\u003coutcome-kebab-case\u003e`\n   - `codex/\u003coutcome-kebab-case\u003e`\n   - (automation exception) `dependabot/*`\n4. Open a PR to `main` with behavior/rationale notes.\n5. Ensure CI is green (`.github/workflows/build.yml`: branch-name check + build + lint + format + test).\n\nFor larger architecture changes, open an issue first to align on the control-plane contract.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclarity-llm-lang%2Fclarity-runtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclarity-llm-lang%2Fclarity-runtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclarity-llm-lang%2Fclarity-runtime/lists"}