Repository navigation
docs: document run modes for the runs API and the MCP start tool - #141
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![mogplex[bot]](https://avatars.githubusercontent.com/in/3107927?s=60&v=4){kind=small}
There was a problem hiding this comment.
Mogplex PR Review
Status: Attention needed
Approve-ready docs PR: the mode documentation is accurate and candid that SAFE does not screen MCP tools, the new #start-a-run anchor resolves, and the 23-to-29 tool-count fix matches the 29 tools catalogued in content/docs/mcp/tools.mdx. One warning: the Endpoint index row for POST /runs still says "Start a Codex or Claude Code run" although this PR adds the mogplex harness to both harness unions. Remaining findings are non-blocking wording and PR-description suggestions; backend-dependent claims rest on Mogplex/mogplex#538, which the author already gates the merge on.
3 findings were added inline.
Suggestions
-
PR description omits the response mode field and the tool-count fix (
content/docs/reference/api.mdx)
The PR body covers the mode semantics and the Mogplex-harness mode refusal, but does not mention addingmodetoMogplexApiRunDetail(line 723) or changing the MCP tool-schema count from 23 to 29 (line 898).A one-line note on each would help future readers trace those lines; the count fix in particular is a drive-by correctness fix (it brings
api.mdxin line with the 29 tools already catalogued intools.mdx) and is easy to miss.
| @@ -741,20 +745,38 @@ Request body: | |||
| type StartRunRequest = { | |||
| repoId: string; | |||
| prompt: string; // At most 100,000 characters. | |||
There was a problem hiding this comment.
Warning: Endpoint index still describes POST /runs as Codex or Claude Code only
This PR adds "mogplex" to harness in MogplexApiRunDetail (line 712) and StartRunRequest (line 747) and documents the Mogplex harness under the "Start a run" section, but the POST /runs row of the Endpoint index table still reads "Start a Codex or Claude Code run.", which now contradicts the request type documented on the same page.
Update the index row (for example, "Start a Codex, Claude Code, or Mogplex agent run."). While there, check the mogplex_start_agent_run row in content/docs/mcp/tools.mdx ("Start a Codex or Claude Code run in a repo sandbox."): if that MCP tool also accepts harness: "mogplex", the row is stale for the same reason; if it does not, no change is needed.
This assumes harness: "mogplex" is accepted by POST /runs per Mogplex/mogplex#538; if it is not, the StartRunRequest union is the part that needs revisiting instead.
| createBranch: boolean; | ||
| }; | ||
| rootDirectory: string | null; | ||
| // The mode the run started with, upper-cased. null: the default, AUTO, or a |
There was a problem hiding this comment.
Suggestion: Clarify when mode is null in MogplexApiRunDetail
The comment on the new mode field ("null: the default, AUTO, or a Mogplex-harness run, which takes no mode") can be misread as null also covering an explicit mode: "AUTO".
If an omitted mode maps to null while an explicit "AUTO" reports "AUTO", say so directly, for example: "null when the request omitted mode (the default, AUTO) or for a Mogplex-harness run, which takes no mode."
Also consider naming what "older Mogplex CLIs" refers to (runs started before mode validation shipped); this page otherwise presents only Codex and Claude Code as harnesses, so the phrase may puzzle external readers.
| `mogplex_start_agent_run` also takes `mode` (`SAFE`, `AUTO`, or `YOLO`) for | ||
| Codex and Claude Code runs. See [Start a run](/reference/api#start-a-run) for | ||
| what each mode allows, including the MCP tools that stay callable in `SAFE`. | ||
|
|
There was a problem hiding this comment.
Suggestion: Rephrase "the MCP tools that stay callable in SAFE"
The new sentence in content/docs/mcp/tools.mdx points readers to the API section "including the MCP tools that stay callable in SAFE", which reads like a curated subset remains callable. The linked section says MCP tools are not screened at all in SAFE.
A phrasing like "including that MCP tools are not screened in SAFE and stay callable" avoids implying a list.
There was a problem hiding this comment.
Mogplex PR Review
Status: Attention needed
Needs discussion rather than changes: the run-mode documentation matches merged Mogplex/mogplex#538 (mode semantics, the SAFE/MCP-tool boundary, mogplex-harness 400s, response typing, and the verified 23→29 tool-count fix), but "Any other value returns 400 BAD_REQUEST" at api.mdx:778 is contradicted by #538, which accepts six legacy CLI modes (single, multi_agent, council, review, test, repair) and runs them as AUTO — a carve-out this PR's own mode comment cites. The author should either add a caveat or confirm the strict phrasing is intentional.
2 findings were added inline.
| Any other value returns `400 BAD_REQUEST`. | ||
|
|
||
| `harness: "mogplex"` runs Mogplex's own agent instead of a CLI. It takes no | ||
| `mode` (sending one returns `400`), always works on its own branch (it creates |
There was a problem hiding this comment.
Warning: 'Any other value returns 400' is contradicted by the legacy CLI modes the mode comment cites
Per Mogplex/mogplex#538 — the implementation this PR documents — normalizeStartRequest also accepts six legacy CLI orchestration modes (single, multi_agent, council, review, test, repair, matched exactly in lowercase), stores them unchanged, and runs them as AUTO, so POST /runs with mode: "single" returns 202 rather than 400.
That is the exact silent-AUTO failure mode #538's validation was added to close, and a caller sending one of those strings today gets a fully permissive run instead of the promised 400.
The page's own mode comment (L720–L725) cites single as a real response value, so the two statements conflict within one section.
Suggest either a caveat here — e.g. "except a few orchestration modes sent by released Mogplex CLIs (such as single), accepted for compatibility and run as AUTO" — or, if the strict phrasing is deliberate policy (#538 keeps legacy modes out of the published schema), drop the single example from the comment so the page doesn't contradict itself.
| Use [Install Mogplex MCP](/mcp/install) for client setup and OAuth. Use | ||
| [MCP tools](/mcp/tools) for all 23 tool argument schemas. | ||
| [MCP tools](/mcp/tools) for all 29 tool argument schemas. | ||
|
|
There was a problem hiding this comment.
Suggestion: PR description omits the 23→29 tool-schema count fix
The PR description covers the mode documentation but not the 23 → 29 change in the MCP transport section.
The new count is correct: tools.mdx lists exactly 29 tools and its intro already said 29, so this fixes a stale cross-reference.
A one-line mention in the PR description would keep the body complete; no doc change needed.
Mogplex PR ReviewStatus: No material issues found Approve-ready docs-only change: the new run-mode documentation is accurate and internally consistent across both files, the mogplex harness value is added everywhere it belongs, and the 23→29 MCP tool-count correction matches the 29 tools actually listed on the tools page.
Affected files
|
This branch was successfully deployed
1 participant
The runs API reference listed
mode?: stringwith no meaning attached. It now spells out the three values and what each lets a Codex or Claude Code harness do. It is explicit thatSAFEkeeps the harness from changing the checkout but doesn't screen MCP tools, so a connection or Mogplex tool that writes can still make changes. It also covers the 400 for any other value and the refusal ofmodefor Mogplex-harness runs.The run detail now documents the
modeit reports: the upper-cased mode the request named, or null when none was sent and for Mogplex-harness runs. It stays typed as a string because the Mogplex CLI's cloud runs report the CLI's own run mode.The reference also stops treating the runs API as Codex and Claude Code only.
harnessaccepts"mogplex"(the API'sMOGPLEX_API_RUN_HARNESSES), so the request and detail types, the endpoint index, and the MCP tool row now include it. A short paragraph covers how a Mogplex run differs: it takes nomodeand always works on its own branch.The MCP tools page now notes that
mogplex_start_agent_runtakesmodeand links to the API reference. Separately, the MCP transport section said there were 23 tool schemas. The tools page lists 29, and that's the real count (14 automation, 11 infrastructure, 4 run tools), so the reference now says 29.This matches Mogplex/mogplex#538, which adds
modeto the MCP tool and validates it in the API. #538 is deployed to production (deploy run 36517937254, 2026-09-29).Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.