Lanser-CLI: Deterministic LSP Orchestration

• Lanser-CLI is a command-line orchestration layer that pins LSP servers to generate deterministic, byte-stable analysis bundles for coding agents and CI pipelines.
• It employs a robust Selector DSL and relocation algorithm for precise code addressing, ensuring resilient mapping even after code edits.
• The system integrates safety envelopes, atomic change protocols, and a process reward function to enhance reliable, reproducible code refactoring and supervision.

Lanser-CLI is a command-line orchestration layer that mediates and “pins” a Language Server Protocol (LSP) server (such as Pyright) for use in autonomous coding agents and continuous integration (CI) pipelines. It transforms ad-hoc JSON-RPC sessions into deterministic, byte-stable artifacts, surfacing verified, machine-checked workflow facts and introducing a process reward functional for process supervision and agent alignment. The system integrates robust code addressing, deterministic response normalization, safety envelopes for refactoring operations, and structured reward shaping, effectively bridging speculative LLM agent planning with the concrete semantics of code bases (Zhang et al., 27 Oct 2025).

1. Architecture and Workflow

Lanser-CLI sits between a language agent and an LSP server connected to a version-controlled file workspace. The architecture consists of four roles:

• Language Agent: Issues high-level intents (e.g., request to rename a function).
• Lanser-CLI Orchestrator: CLI-first orchestration, offering single-flight caching, JSON-RPC tracing, and emission of normalized “Analysis Bundles.”
• LSP Server: Computes verified facts including definitions, references, diagnostics, and code-action previews.
• Workspace: Version-controlled source files representing the project under modification.

The system ensures that the LSP server is pinned by version and position encoding, that all file change notifications (didOpen/didChange) are synchronized deterministically, and that all in-flight requests are memoized, producing canonical Analysis Bundles. Each canonical bundle $B$ is defined so that, under fixed workspace $S$, binary $V$, configuration $\Pi$, and request $Q$, the output is byte-identical across runs ($\text{bundleId}(B)$ is invariant), thus establishing determinism under frozen snapshots.

2. Robust Code Addressing with Selector DSL

Traditional file:line:col addressing is insufficiently stable under code changes. Lanser-CLI provides a Selector DSL (“PositionSpec”) allowing four classes of selectors, formally expressed in EBNF:

• Cursor: Line/column address within a file (path@Lx:Cy).
• Range: Start/end range within a file (path@R(x,y->u,v)).
• Symbolic: Symbol and role, e.g. "py://pkg.mod#Class.method:sig".
• AST Path: Paths over the AST, e.g. ast://[module=pkg.mod]/[class=C]/[def=m].
• Content Anchor: Snippet-anchored content with context window and content-hash, e.g., anchor://path#"<snippet>"?ctx=N.

A principled relocation algorithm supports mapping stale selectors after code edits. Candidate resolutions are ranked deterministically via a feature-weighted score combining AST similarity, token Jaccard, module, proximity, etc., and the highest scoring match is reported unless ambiguity is detected. Under frozen snapshots, symbolic and AST selectors resolve uniquely or yield an error code.

3. Deterministic Analysis Bundles

Each CLI command emits an “Analysis Bundle” $B$ that is a canonical, schema-validated JSON envelope formalized by:

$$B \coloneqq (\mathrm{version},\,\mathrm{bundleId},\,\mathrm{status},\,\mathrm{request},\,\mathrm{resolution},\,\mathrm{facts},\,\mathrm{edits},\,\mathrm{processReward},\,\mathrm{environment},\,\mathrm{capabilities},\,\mathrm{meta})$$

Key bundle elements include:

• bundleId: SHA256 hash of JCS-canonicalized JSON minus volatile fields.
• environment: Snapshot of LSP version, config digest, Python binary, and platform.
• facts: Definitions, references, diagnostics, and hover information, verified by the LSP.
• edits: Proposed or executed refactorings, diffs, and mutations.
• processReward: Process supervision metrics (see Section 5).

Stability rules enforce canonical order (by URI and offset), UTF-8/JCS encoding, and dual coordinates when the CLI and LSP server encoding differ.

4. Safety Envelope for Code Mutations

Lanser-CLI imposes guardrails on code-editing operations (e.g., renames, code actions):

• Preview-first (--dry-run): All mutations default to preview; diffs emitted in the bundle.
• Workspace jail: Edits are confined to the project root, with path filters for allow/deny.
• Dirty worktree refusal: Refuses to apply changes atop a dirty VCS state without explicit override.
• Atomic apply: Code changes applied with atomic filesystem operations or git diff3 merges, preserving metadata.
• Indexing mismatches explicit: Surface explicit errors if content/indexing diverge between CLI and LSP.

The “Guarded Rename” protocol emits a preview, unifies commit, and coalesces diagnostics, with all actions captured in Analysis Bundles.

5. Process Reward Functional

Lanser-CLI operationalizes process-level reward shaping using machine-verified facts. For each agent step $t$, define:

• $D_t \in \mathbb{N}$: Number of relevant diagnostics
• $S$0: Binary safety clearance (all guardrails passed)
• $S$1: Selector disambiguation confidence

The process reward is:

$S$2

with tunable $S$3.

Process reward metadata (version, components, weights, and explanations) are recorded for each bundle. The score supports both online computation (real-time upon responses) and offline computation via the deterministic artifacts, enabling counterfactual replay, batch analysis, and process-supervised RL.

6. Formal Properties and Determinism

Proposition 2.1 establishes that, fixing the workspace, LSP binary, configuration, and position encoding, Lanser-CLI emits byte-identical bundles and bundleIds for a fixed request. Determinism is ensured by deterministic sorting, canonicalization, explicit environment pinning, and exclusion of volatile fields. The LSP server, treated as a pure function over this tuple, is required for invariant outputs.

Proposition 2.2 (Monotonicity) shows that, under fixed weights, the reward update $S$4 is non-negative if diagnostics do not regress, safety is monotonic, and selector confidence does not decrease. Each term is guaranteed non-negative under these conditions, supporting process supervision and reliable counterfactual evaluation.

7. Applications and Example Workflows

Typical applications of Lanser-CLI include:

• LLM coding agent supervision: Enabling planner-act agent loops (e.g., GPT Codex, Claude Code) to leverage LSP-verified code facts and process rewards for navigation and refactoring.
• CI gating for codebase-wide changes: Deterministic, audit-friendly application and replay for large-scale code refactorings.
• Policy learning and evaluation: Offline, byte-identical replay of agent workflows, supporting process-supervised RL and counterfactual analysis.

Example invocation patterns:

Command Example	Functionality	Notable Outputs
lanser def ...	Retrieve definition facts for symbol	facts.definitions, processReward
lanser rename ... --dry-run	Preview and diff for a guarded rename	edits.diff, processReward
lanser trace replay ...	Replays trace, emits bundles and rewards	Byte-identical bundles and rewards

This suggests that Lanser-CLI facilitates high-integrity, LSP-mediated agent workflows where both developer tools and machine agents benefit from actionability, verification, and reliable process-level feedback.

Reference: (Zhang et al., 27 Oct 2025)