feat(runtime-host): discover peer mesh routes (#4055) * feat(runtime-host): discover peer mesh routes Sign short-lived route records with each libp2p identity and reconcile them between admitted peers. Feed only verified routes into the shared endpoint while preserving the target PeerId and Runtime Host credential authority. Cover route changes, removal propagation, restart recovery, native identity binding, and the installed CLI composition. Generated-by: Codex * fix(runtime-host): share peer endpoint with mesh discovery Serve application and Mesh control traffic from one peer identity, preserve verified bootstrap routes, and keep removal convergence scoped to the removed member. Generated-by: OpenAI Codex * refactor(runtime-host): centralize peer route cache Store each signed peer route once per node, filter it through active Mesh rosters, and allow expired route sequences to restart without weakening fresh-route rollback protection. Generated-by: OpenAI Codex * refactor(runtime-host): keep mesh routing in mesh node Use the route resolver only for application connections so Mesh control has one target-composition authority. Generated-by: OpenAI Codex * fix(runtime-host): serialize mesh route refresh on join Reuse the node's local route refresh while joining so background reconciliation cannot publish a different fact at the same sequence. Generated-by: OpenAI Codex * refactor(runtime-host): centralize mesh route sequencing Allocate every local route sequence from the node-level cache instead of accepting caller-supplied values. Generated-by: OpenAI Codex * fix(runtime-host): serialize connects per peer Queue application and Mesh-control dials targeting the same PeerId so the shared native endpoint never rejects a valid concurrent caller as already in progress. Generated-by: OpenAI Codex * fix(runtime-host): refresh mesh proofs during reconciliation Refresh the local signed route before each synchronization page so earlier unreachable members cannot starve later healthy peers with an expired proof. Add a deterministic long-round regression covering the real per-peer dial budget. Generated-by: OpenAI Codex
[!NOTE] Apache Maka (Incubating) is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator PMC. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision-making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. DISCLAIMER-WIP records the issues the project is currently aware of.
[!IMPORTANT] Maka is under active development. The macOS Apple Silicon desktop build is an early public release; data formats, CLI commands, and experimental capabilities may still change.
Read Maka Backend Architecture for the design.
| Entry point | Best for | Current capability |
|---|---|---|
| Desktop | Daily interaction, file and Artifact workflows, model and permission setup | Electron + React with streaming sessions, tool timelines, branching, search, and recovery |
| TUI / CLI | Using Maka in the current project directory or running one non-interactive Turn | maka, maka run; shares workspace and model connections with Desktop |
| Eval | Reproducible benchmark experiments across Maka and external subjects | maka eval run <spec> --out <directory> |
Read, Write, Edit, Bash, Glob, Grep. Computer Use and catalog skills are optional and not on by default;Apache Maka has not made an Apache release yet. Everything currently published from this repository or from a package registry was produced before or during incubation, is not an Apache Software Foundation release, and has not been reviewed or voted on by the Incubator PMC.
Once Apache releases exist, the official release is the source release published by the ASF and approved by the podling PPMC and the Incubator PMC. A package built from that source and distributed elsewhere, for example through a package registry or as a Desktop installer, is a convenience artifact rather than the release itself, and it is valid only when it is built from an approved source release. .github/ASF_SOURCE_RELEASE.md holds the candidate contract, signing path, and verification steps.
Until an approved source release exists, this README recommends no prebuilt download. Build and run Maka from source as described below. Desktop currently targets Apple Silicon Macs (arm64). Intel Macs and Linux are not supported yet. Windows is an unsigned preview, not a supported release tier.
packageManager is npm 11);ripgrep, used by Runtime's Grep tool.git clone https://github.com/apache/maka.git cd maka npm ci npm run dev
npm run dev starts the Desktop development environment with HMR. To build every workspace before starting Electron, use:
npm run dev:full
If dependencies were installed with ELECTRON_SKIP_BINARY_DOWNLOAD=1, install the Electron platform binary before starting:
node node_modules/electron/install.js
Maka does not bundle a shared model account. On first launch:
Settings → Models;The app distinguishes configured, send-ready, and experimental connection states. An account flow that is not wired into Runtime is not presented as a usable model.
For the public npm package, see the CLI installation and usage guide. The commands below run the development CLI from a source checkout.
Build the workspaces first:
npm run build
Then start the TUI or run one Turn:
npm run cli:dev npm run cli:dev -- run "Summarize this repository and identify its most important risk" npm run cli:dev -- run --graph "Implement two independent slices, integrate them, then review the result" npm run cli:dev -- --help
The TUI also accepts /graph on, /graph off, and /graph <task>. Non-interactive --graph runs wait for the durable Graph to finish before printing the final supervisor output. Graph implementation operators use isolated Git worktrees, so the source project must be a clean Git worktree.
The repository CLI uses the same Maka Dev profile as a development Desktop build. The released maka binary continues to use the Maka profile; the two profiles are not copied or synchronized automatically. Evaluation specs and adapters live in packages/eval.
The backend spine is:
Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun ↓ Model + Tool Runtime → Runtime Event Log ↓ Context / Session / UI projections Experiment → Cells → Attempts → Results ↓ Runtime Host executes Maka subjects
Start with ARCHITECTURE.md. It provides the system map, code boundaries, problem-oriented reading paths, and six bilingual deep dives.
apps/desktop/ Electron main / preload / React renderer packages/core/ Pure contracts for Sessions, Events, Permissions, and Connections packages/storage/ SQLite operational state, configuration, and payload stores packages/mcp/ Provider-neutral Model Context Protocol client integration packages/runtime/ AgentRun, model adapters, tools, context, and recovery packages/runtime-host/ Single-owner Runtime Host lifecycle, protocol, and client bootstrap packages/eval/ Experiment cells, attempts, results, and executor/subject adapters packages/computer-use/ Computer-use backend selection, host lifecycle, and protocol adapters packages/cli/ TUI and non-interactive CLI packages/ui/ Shared conversation, Markdown, Artifact, and UI primitives docs/ Architecture, product, security, privacy, and test contracts scripts/ Build hygiene, visual checks, smoke tests, and release helpers
Workspace data lives under Electron userData by default:
<Electron userData>/workspaces/default/ runtime.sqlite connection-catalog.json credential-vault.json settings.json artifacts/
credential-vault.json), readable only by your OS account. The renderer never sees them.runtime.sqlite is the live record. Older JSONL transcripts and Electron safeStorage credential files are not imported; an upgraded workspace can show empty threads, and those credentials must be entered again.MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 only if you want Desktop Safe resume, CLI /resume, and startup auto-resume — those calls hit the model and use tokens.Details: SECURITY.md, privacy, resume.
Before sending a change, read CONTRIBUTING.md.
Common repository-level commands:
npm run build npm run typecheck npm test npm run check:release
Run one workspace in isolation:
npm --workspace @maka/runtime test npm --workspace @maka/eval test npm --workspace @maka/desktop test
Use refresh:model-metadata to fetch the current catalog from models.dev, update the committed snapshot, and regenerate the derived TypeScript files. A refresh fails closed when any committed model, capability, provider override, or pricing field disappears; after reviewing an intentional upstream removal, acknowledge it with npm run refresh:model-metadata -- --accept-upstream-removals. sync:model-metadata is intentionally offline: it only regenerates those files from the committed snapshot. Keep access-path-specific overrides in model-metadata.ts; do not edit the generated files by hand.
npm run refresh:model-metadata npm --workspace @maka/core test
Desktop real-window and visual verification:
npm --workspace @maka/desktop run e2e npm --workspace @maka/desktop run smoke:real-window
Before submitting code, run typecheck, build, and focused tests proportionate to the change, followed by git diff --check.
Maka is licensed under the Apache License 2.0. See NOTICE for attribution information. Third-party components remain subject to their respective licenses and notices.
Apache Maka, Maka, Apache, the Apache feather, and the Apache Maka project logo are either registered trademarks or trademarks of The Apache Software Foundation.