Repository navigation
mcpx: public Go API surface + compatibility-promise proposal (split from #1877) #2119
Description
Split from #1877 (triage task 2771, 2026-10-29); parent tracker #1885 (extensibility).
What is needed
A decision-ready proposal for mcpx's public Go API surface — step 1 of #1877's sequence (public Go package → C ABI → WASM, each step only if the one before it has a caller).
Confirmed at triage (2026-10-29, current main): there is no public Go API at all — pkgs/mcpx top level is cmd/, daemon/, internal/, plugin/, docs/; every implementation package is under internal/ and cannot be imported by another module. Today "embedding" means exec the binary or speak /v1 over the socket.
The proposal must name
- The candidate public packages (smallest surface that serves a real first caller) and the first caller each serves.
- The compatibility promise that attaches to them.
- Honest weighing of the status-quo alternatives (exec the binary;
/v1over the socket) — if they suffice for the named callers, say so and close the sequence. - Sequencing for the C ABI (
-buildmode=c-shared/c-archive) and WASM (wasip1reactor via the same exported surface), per mcpx: embedding mcpx -- a public Go API, the C ABI, WASM, and mcpx as its own upstream #1877.
Out of scope
- Implementing the API, C ABI, or WASM build (a follow-up implementation packet follows the decision).
- The self-connection loop guard — split 1 from mcpx: embedding mcpx -- a public Go API, the C ABI, WASM, and mcpx as its own upstream #1877, queue task 3108.
Acceptance
- Proposal posted (here or on mcpx: embedding mcpx -- a public Go API, the C ABI, WASM, and mcpx as its own upstream #1877) covering points 1–4 with file:line evidence for claims about the current package layout.
- An implementation packet is enqueued once the surface is decided, or the decision is escalated with the proposal attached.
Acceptance criteria
- A proposal is posted (here or on mcpx: embedding mcpx -- a public Go API, the C ABI, WASM, and mcpx as its own upstream #1877) covering: the candidate public packages and the first caller each serves; the compatibility promise that attaches to them; an honest weighing of the status-quo alternatives (exec the binary;
/v1over the socket); and sequencing for the C ABI and WASM steps — with file:line evidence for claims about the current package layout. - An implementation packet is enqueued once the surface is decided, or the decision is escalated with the proposal attached.
Activity
developing-today commentedon Oct 29, 2026
CODE-1021
dezren39 commentedon Oct 29, 2026
Intake review
internal/) was confirmed at that triage against current main. This is a decision-ready proposal task, not an implementation.🤖 Fleet monitor intake enrichment, 2026-10-29. Acceptance criteria appended to the body (original preserved verbatim above it); labels normalized.
1 remaining item
dezren39 commentedon Nov 1, 2026
🤖 Agent note · picked up
dezren39 commentedon Nov 1, 2026
🤖 Agent note · escalated
Proposal (evidence checked on main
5c172f3d)Current surface
mcpx, but it only exportsAgentDocs string(pkgs/mcpx/agentdocs.go:1-20;go doc .). It is agent documentation data, not an embedding or client API.internal/cli,internal/config, andinternal/daemon(pkgs/mcpx/cmd/mcpx/main.go:14-17). The useful daemon entry points (Options,NewServer,Handler,InProcessHandler) are ininternal/daemon(server.go:174-201, 517-540), so external Go modules cannot import them./v1is already the language-neutral daemon contract. Its operation table generates routes, MCP tools, CLI commands and OpenAPI (internal/api/ops.go:1-13).docs/http-api.md:171-190says no SDK is published and recommends generating a client withoapi-codegen;:195-214documents the live OpenAPI source and Unix-socket transport caveat.Candidate packages and first callers
pkg/client— typed Go client for/v1. Generate from OpenAPI rather than hand-copying the operation table. First caller would be a named external Go host that needs typed daemon calls. No such consumer is named in mcpx: embedding mcpx -- a public Go API, the C ABI, WASM, and mcpx as its own upstream #1877, mcpx: public Go API surface + compatibility-promise proposal (split from #1877) #2119 or tracker mcpx: extensibility -- plugins, hooks, tool sources, embedding (tracker) #1885; a generated client from the existing spec already serves the generic case.pkg/daemon— optional in-process daemon facade. It could expose a small constructor, listener/handler and context-bound shutdown contract without re-exportinginternal/daemon.Options. First caller would be a Go host that cannot use a child process or local socket and needs daemon lifecycle in its own process. No such host is identified; current internal tests are not a reason to publish it.config,api, or implementation packages wholesale. Add a public package only for a concrete caller and keep the rest underinternal/.Compatibility promise if a package is approved
Keep
internal/*private with no compatibility promise. For any new public package, document the exact supported surface. Recommended policy: explicitly experimental duringv0.x(breaking changes allowed only with a minor-version bump and migration note); freeze the contract atv1.0.0and use SemVer thereafter. The module is currently0.1.0; Go submodule tags must also follow thepkgs/mcpx/vX.Y.Zpath described in decision 0005 §3, separately from the human-facingmcpx/vX.Y.Zrelease tag.Alternatives and sequencing
/v1over the Unix socket: recommended for general automation. It is language-neutral, has a generated OpenAPI contract, and keeps daemon ownership/lifecycle outside the caller. Generate Go types/client when needed. This is sufficient for every caller currently named in the issues.c-archive; usec-sharedonly when runtime loading is required. Awasip1reactor can only cover pure analysis that needs neither sockets nor subprocesses. These remain after the public Go decision, not part of it.Recommendation and decision requested
Default: do not enqueue implementation yet. Keep exec and
/v1as the supported surfaces until a real first Go caller demonstrates why they are insufficient. If proceeding speculatively, start withpkg/clientonly; do not expose the stateful daemon until a host requiring in-process lifecycle is named. This decision commits to a long-lived public API and a pre-1.0 compatibility policy, so I am escalating the choice to Drew: either (A) defer/close #2119 until a caller is named, or (B) approve the speculativepkg/clientsurface and the experimental-v0.xpolicy above. No implementation packet has been enqueued.dezren39 commentedon Nov 3, 2026
RULING (Muse, acting for Drew, 2026-11-03): defer — no speculative public pkg/client and no experimental v0.x compatibility policy until a concrete first Go caller shows exec and /v1/OpenAPI are insufficient. Task 3112 closed with this ruling.
dezren39 commentedon Nov 3, 2026
Closed as deferred in the 2026-11-03 coverage pass, per the 2026-11-03 ruling (Muse, acting for Drew): the speculative public Go API client is DEFERRED — no compatibility promise is made for a client that does not exist yet. Task 3112 is done. Reopen when a real external client appears.
dezren39 commentedon Nov 3, 2026
Triage task 7453 closed as
already_done— no code changed, no worktree, no branch.Fresh check 2026-11-03T12:05Z: #2119 is CLOSED (2026-11-03T10:05:26Z). The proposal was settled by the 2026-11-03T09:22Z ruling (Muse, acting for Drew): the speculative public Go API client and any v0.x compatibility promise are deferred until a concrete external Go caller shows
exec+/v1/OpenAPIare insufficient; queue task 3112 is done.Label repair: removed the stale in-flight/escalation labels this packet was filed against (
status/blocked,queue/blocked,user/escalated). Nowork/*label was present. Nothing is in flight; reopen only if a real external Go client appears.