Manch

Manch (मंच) — the stage. The place where the puppets perform and the audience connects. An open, framework-agnostic substrate for hosting AI agents.

Manch is reusable plumbing for hosting AI agents. It exists so the products built on top of it spend their effort on domain logic, not infrastructure. It is domain-free by rule: nothing in Manch knows what a contract, a case, or a patient is.

Status: design + skeleton. Core APIs are not yet stabilised. See Status & first milestone.

Is:

• A set of Rust crates you embed as a library to host AI agents.
• An extension surface: implement a trait, register it, done — no forking.
• A bridge to external agents over ACP (Agent Client Protocol) and tools over MCP.
• Optionally, a thin self-hostable server (chat + Telegram engine) built on the same core.

Is not:

• A web service you must run (the server is one optional consumer, not the center).
• A model reseller or billing system.
• A product with domain knowledge (legal/health logic lives in consumers, never here).

• Library-centric, not server-centric. The core is headless and framework-free. A Tauri app, a CLI, a server, and any domain product all embed the same core. The application is a thin, disposable consumer.
• Functional / DI-free leaning. Capabilities are passed explicitly and composed, not injected through a runtime container. dyn Trait is used only at genuine extension boundaries (the rim), not throughout (the core). FP core, thin polymorphic rim.
• Follow standards, own the ergonomics. ACP is already an open standard (authored by Zed, Apache-licensed, community-governed). Manch does not reinvent it — it builds the reusable, framework-agnostic host that the ecosystem lacks.

Nothing below the application layer may name a domain. No "legal", no "health", no "contract", no "patient".

Domain products are consumers that implement Manch's traits in their own repositories and register them at startup. The test:

Can a consumer depend on manch-core without pulling in Tauri or anything domain-specific? If yes, it's a library. If no, logic has leaked into the shell — pull it back down.

The moment a domain noun appears inside a manch-* crate, it has stopped being substrate.

┌─────────────────────────────────────────────────────────────┐
│  CONSUMERS  (own repos · domain-specific)                     │
│                                                               │
│   domain products    manch-server      manch-app             │
│   (own Tools)        (open, self-       (Tauri reference)     │
│                       hostable)                               │
└───────────────┬───────────────────────────────────┬──────────┘
                │  register Agents / Tools / Channels via builder()
                ▼                                     ▼
┌─────────────────────────────────────────────────────────────┐
│  manch-core   — runtime: registries + prompt/tool loop        │
│                 framework-free · domain-free · the seam gate  │
└───────┬───────────────┬────────────────┬───────────────┬─────┘
        │ implements     │                │               │
        ▼                ▼                ▼               ▼
┌───────────────┐ ┌────────────┐ ┌──────────────┐ ┌──────────────┐
│ manch-protocol│ │ manch-acp  │ │manch-channels│ │ manch-memory │
│ THE CONTRACTS │ │ ACP host   │ │ CLI/Telegram │ │ SQLite store │
│ Agent  Tool   │ │ (on official│ │ /webhook     │ │ + context    │
│ Channel       │ │  acp crate)│ │ (Channel)    │ │  assembly    │
│ MemoryStore   │ │            │ │              │ │  (the seam)  │
└───────────────┘ └────────────┘ └──────────────┘ └──────────────┘
        │                                                │
        └───────────────────┬────────────────────────────┘
                            ▼
            ┌────────────────────────────────┐
            │ kathputli  (actors over tokio)  │  ← already published,
            │ katha      (event sourcing)     │     now with a home
            └────────────────────────────────┘

Dependencies flow strictly downward. Lower layers never depend on upper layers. katha and kathputli have zero internal dependencies.

Everything an external developer extends is a trait in manch-protocol.

1. In-process (Rust): implement a trait, register with Manch::builder(). Typed, fast, compile-time. Best for Rust contributors and for domain products.
2. Out-of-process (any language): speak ACP; manch-acp hosts you. No recompile, no source access. This is the primary, language-agnostic "build on it" path.

Manch follows Zed's external-agents model: a session runs against either a key you bring or an agent CLI already on your machine. Either way it's just a registered Agent — one interface, two implementations. A BYOK provider and an external CLI agent both implement the same [Agent] trait and both stream back ACP's own event vocabulary, so the core and the UI never branch on which kind they're talking to. (Zed proves this works: its native agent and its external ACP agents share one connection abstraction.)

1. BYOK (bring your own key) — a direct provider connection (Claude / GPT / Gemini / local Ollama). manch-core owns the prompt → tool → re-prompt loop and supplies host-registered Tools. You hold the key; Manch never resells.
2. BYOC (bring your own CLI) — an external agent (Claude Code, Gemini CLI, Codex, …) launched as a subprocess and driven over ACP by manch-acp. The external agent owns its own auth, model selection, and tools; Manch is the ACP client and streams its events through. No recompile, no source access.

Every host-registered Tool declares a tier(): Read (safe to auto-execute) or Draft (a proposed mutation). Three things about this are deliberate:

• tier() is required, with no default. A default of Tier::Read would hand auto-execution to any tool author who never stopped to consider the question. Declaring risk is not optional.
• There is no Never variant. A tool that must never run is a tool that is not registered — absence is not something a runtime needs to check for, so encoding it as a tier would only add a state nothing can reach.
• A Draft call suspends the turn; it does not block a thread. When a PermissionPolicy wants a human, manch-core returns TurnOutcome::AwaitingApproval and the caller resumes later with a decision — the suspension can outlive the request, cross a process boundary, or wait on a Telegram reply. Consumers who just want the linear "ask, then run" shape can use Manch::handle_with_approver, a thin loop over handle/approve for exactly that case.

Found during implementation; documented rather than hidden.

• A discarded batch can leave a UI showing a call that has no stored record. When a turn issues several tool calls and a later one in the same batch errors, the whole batch is dropped from memory — MemoryStore is append-only with no compensating delete, so atomicity comes from not writing yet, not from rolling back. But a call earlier in the batch that already succeeded has already emitted ToolCallStatus::Completed to the event sink before the batch's fate is known. A UI driven off that stream can therefore show a call as completed that, moments later, corresponds to nothing in the persisted transcript.
• Gemini tool-call ids are synthesised, and repeat calls are paired by order, not identity. Gemini's wire format supplies no call id, so Manch synthesises one from the part's position in the response. Gemini also keys functionResponse (the result) by tool name, not by id — so when one turn calls the same tool twice, which result belongs to which call is genuinely ambiguous on Gemini's own wire. Manch preserves issue order (never reordering or merging), which is the best available reading, not a guaranteed-correct one.

Manch's BYOK path does not sit on a Rust LLM framework (e.g. rig). Every serious agent host we surveyed — Zed, ZeroClaw, and AionUi's aionrs engine — hand-rolls thin per-provider clients over reqwest, and Manch does the same. The reason is control: the provider features that matter (prompt-caching betas, OAuth / subscription auth, reasoning params, the Responses API, streaming quirks) land in a framework — if ever — long after they ship in the raw API, and auth schemes like Anthropic OAuth, Bedrock SigV4, or Vertex service accounts don't fit a one-size abstraction at all.

The work is smaller than it looks, because providers cluster into a few wire dialects, not N bespoke integrations:

So ~three hand-rolled clients plus one OpenAI-compatible config layer cover the entire list. Per-provider quirks (max-tokens field name, base URL, schema sanitisation) are data, not branches.

Pointing a client elsewhere. Every BYOK agent resolves its endpoint as explicit argument → MANCH_{PROVIDER}_BASE_URL → vendor default, and the catalog endpoint is derived from the same base as the completion endpoint:

// an OpenAI-compatible third party, or a self-hosted gateway
OpenAiAgent::new(key, None).base_url("https://api.fireworks.ai/inference/v1");

# same effect for every OpenAI-dialect agent in the process
export MANCH_OPENAI_BASE_URL=https://api.fireworks.ai/inference/v1

The explicit argument wins deliberately: a server routing several tenants through different proxies needs per-agent endpoints in one process, which an environment variable alone cannot express.

Listing models, though, is a free function — there is no instance list_models, so an agent built with .base_url(proxy) does not redirect the catalog on its own. A caller that overrode the base per agent (rather than via the env var, which list_models does read) must thread that base through itself, reading it back with base():

let agent = OpenAiAgent::new(key, None).base_url("https://api.fireworks.ai/inference/v1");
let models = manch_llm::list_models_at("openai", &key, Some(agent.base())).await?;

Token usage. Providers report token counts differently — Anthropic splits input and output across two frames, Gemini repeats a running total per chunk, OpenAI sends one final block (and only when asked). Manch normalises them to AgentEvent::Usage and forwards them as they arrive without accumulating. This is for display, never for billing: a managed tier meters at its own proxy rather than trusting a client-side total.

Provider roadmap: Anthropic → OpenAI → OpenAI-compatible (lights up xAI / Groq / Together / Fireworks / vLLM / LiteLLM at once) → Gemini, Ollama → Bedrock / Vertex on demand.

rig is not banned. If it ever saves real work for one provider it can be dropped in as a single impl behind the same trait — never as the load-bearing interface.

How a CLI agent gets discovered (a superset of Zed — registry + config + detection):

// Zed-compatible agent config shape
{
  "agent_servers": {
    "my-agent": { "command": "node", "args": ["~/agent/index.js", "--acp"], "env": {} }
  }
}

Prompt flow

Channel/UI → manch-core.prompt(agent_id, session, message, sink)
           → MemoryStore.assemble_context(...)        // pluggable strategy
           → Agent.prompt(context, tool_schemas, sink)
           → [stream] AgentEvent::ToolCall
               → manch-core dispatches Tool.call(args)
               → feeds ToolResult back, re-prompts
           → AgentEvent::Done
           → events stream back out to the originating Channel/UI

Extension flow

A domain product NEVER edits Manch source. It:
  1. implements Tool (and/or Agent/Channel/MemoryStore) in its OWN repo
  2. registers via Manch::builder().tool(Arc::new(MyDomainTool))
  3. ships its own binary that embeds manch-core

That single .tool(...) call is the entire open-substrate / closed-moat boundary, expressed in code.

An internet-reachable agent with shell/file tools and a Telegram command path is a real RCE surface. The self-hostable server ships secure-by-default:

• Auth on by default (token-based); bound to localhost unless explicitly opened.
• Telegram bot tokens scoped; inbound commands authenticated to a known user.
• Shell / file-system tools off or sandboxed unless explicitly opted in.
• Loud README warning about the exposure footgun.
• Secrets never hardcoded; user-supplied API keys encrypted at rest, never logged.

• Model billing / gateway — a separate project. End-users connect directly to Gemini / Claude / OpenAI with their own credentials and pay the provider. Keeping it out of Manch avoids the reseller-liability and account-coupling traps.
• Domain logic — see The one rule.
• A mandatory server — the server is optional; the library is the product.

Each name maps to its function. Katha records, Kathputli performs, Manch presents.

just setup     # install JS deps, generate proto bindings, install git hooks
just ci        # run everything CI runs: fmt, clippy, tests, JS lint/test/build
just test      # all tests (Rust + JS)
just --list    # see all recipes

Git hooks (via Lefthook) run fmt + lint on commit and clippy + tests on push. manch-protocol will be published to crates.io by release-plz. Nothing is published yet: the workflow is parked (manual trigger only) until a consumer has exercised the crate surface at runtime. Tagging vX.Y.Z builds desktop installers and the server Docker image (ghcr.io/manchhq/manch-server).

Using an AI coding agent? See AGENTS.md — the tool-agnostic guide (commands, repo map, conventions). Claude Code, Gemini CLI, and Copilot read their own pointer files (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md), all of which defer to AGENTS.md.

Status: design + skeleton. Core APIs not yet stabilised.

First milestone (proves the whole thesis):

One prompt — "What is the capital of India?" — answered correctly through both agent paths behind the single [Agent] interface:

1. BYOK Anthropic, via Manch's own hand-rolled Messages-API client (no rig).
2. Claude Code, launched as a subprocess and driven over ACP.

Same question, same interface, two implementations. No streaming, no tools yet — just proof that the unified seam holds across a raw provider and an external CLI.

If that works, every other consumer (the server, any domain product) and every other provider is just a different Agent/Tool registered on the same spine.