apomesh-vertical-coding-assistant

apomesh-vertical-coding-assistant is a substrate-coupled vertical: a use-case that sits beside the substrate and specializes it for coding workflows, rather than living inside it. It plugs coding-specific tools into the substrate’s tool registry behind the standard Tool port — a Language Server Protocol (LSP) client and four code-intelligence tools, a tree-sitter AST query tool, and a coding-typed view over the substrate’s generic procedural-memory sections. The substrate ships the mechanisms (tool registry, sandboxed CLI execution, procedural-memory storage); this crate composes them into coding surfaces so the substrate stays domain-neutral. It is compiled only into deployments that opt in via the coding-assistant Cargo feature — default builds never link its LSP or tree-sitter dependencies. Touch it when you change how a coding agent reads a codebase.

Position in the workspace

• Layer: vertical (substrate-coupled use-case). See Agent configuration for how a vertical’s tools reach a session.
• Depends on: apomesh-orchestrator (the tool registry + workspace path resolver it registers into), apomesh-substrate (the Tool port and the generic ProceduralSections it projects), and apomesh-protocol (the wire types). Plus the external lsp-server / lsp-types (the LSP JSON-RPC wire) and tree-sitter with the per-language grammar crates.
• Consumed by: only apomesh-orchestrator-bin — an optional, feature-gated dependency. No other workspace crate links it; a default daemon build excludes it entirely.

What it owns

• The LSP tools — four read-only Tools sitting atop one LspClient per running server: lsp.find_definition, lsp.find_references, lsp.diagnostics, lsp.type_at. Registered together by register_lsp_tools.
• The AST query tool — ast.query (AstQueryTool), a tree-sitter-backed structural query over a single file. Registered by register_ast_tools.
• The LSP wire client — LspClient owns the vertical’s wire to a language server: JSON-RPC framing, request correlation, and capability negotiation. It does not own path safety — tools compose it with the substrate’s workspace path resolver.
• The server lifecycle — LspServerHandle resolves, spawns, and handshakes one language server per (workspace, language), shared across the four tools; detect_language picks the workspace’s language from marker files.
• The AgentMd typed view — a coding-vocabulary projection over the substrate’s generic ProceduralSections (## Build → build_command, ## Test → test_command, ## Conventions, ## Do Not Touch), via From<&ProceduralSections>.

It does not own the sandbox policy, the Tool port, or procedural-memory storage — those are the substrate’s; this crate composes them.

Tool inventory

Tool id	Type	Contract
ast.query	AstQueryTool	tree-sitter structural query over one file — Rust, Python, TypeScript, JavaScript
lsp.find_definition	LspFindDefinitionTool	go-to-definition at a position
lsp.find_references	LspFindReferencesTool	find-all-references for a symbol
lsp.diagnostics	LspDiagnosticsTool	diagnostics for a file
lsp.type_at	LspTypeAtTool	hover / type-at-position

The LSP tools cover Python, Rust, and TypeScript (the languages with a resolvable server); the AST tool additionally covers JavaScript.

Public surface

Verified against HEAD. A curated map, not the full rustdoc.

• register_ast_tools — registers ast.query into a ToolRegistry against a workspace path resolver.
• register_lsp_tools — registers the four LSP tools against a shared LspServerHandle.
• LspServerHandle — new_for_language(language, workspace_root) resolves the binary, spawns it, completes the handshake; returns Ok(None) when no server is installed.
• detect_language — picks the workspace LspLanguage from marker files (pyproject.toml > Cargo.toml > tsconfig.json), or None.
• LspLanguage — the closed enum of LSP-covered languages; carries the default binary name and the APOMESH_LSP_SERVER_<LANG> override name.
• LspClient / LspError — the LSP JSON-RPC client and its typed error surface.
• AgentMd — the coding-typed AGENT.md view, built From<&ProceduralSections>.

Usage

The tools are not called directly — the orchestrator daemon binary wires them in at boot when built with the feature. Enable it:

# Default build — coding-assistant deps are NOT linked
cargo build -p apomesh-orchestrator-bin

# Coding-assistant deployment
cargo build -p apomesh-orchestrator-bin --features coding-assistant

With the feature on, the binary registers ast.query, then detects the workspace language and — if a server is available — spawns it and registers the four LSP tools. Point a language at a specific server binary with the per-language override (otherwise the default name is searched on PATH):

# Default binaries: pylsp / rust-analyzer / typescript-language-server
export APOMESH_LSP_SERVER_RUST=/opt/rust-analyzer/bin/rust-analyzer

A missing server binary is not fatal: the binary logs and skips LSP-tool registration, so a non-coding deployment boots without any language server installed.

Related

• Concepts: Agent configuration — how a vertical’s tools reach a session.
• Reference: apomesh-substrate-tools (the tool plane it registers into), apomesh-orchestrator-bin (the feature-gated assembly point), apomesh-vertical-deep-research (the sibling vertical).