Skip to content

docs: document run modes for the runs API and the MCP start tool #141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
charlesrhoward merged 7 commits into from
Sep 29, 2026
Merged

docs: document run modes for the runs API and the MCP start tool #141

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
335a960
docs: document run modes for the runs API and the MCP start tool
charlesrhoward Sep 29, 2026
a54ca6a
docs(api): show mode on the run detail
charlesrhoward Sep 29, 2026
9ff3638
docs(api): say what YOLO still blocks on Claude Code
charlesrhoward Sep 29, 2026
fb08e6c
docs(api): document the mogplex harness and fix the MCP tool count
charlesrhoward Sep 29, 2026
31eaca7
docs: name the Mogplex harness in the run indexes; clarify null mode
charlesrhoward Sep 29, 2026
9f07b66
docs(api): note the CLI run modes the API still accepts
charlesrhoward Sep 29, 2026
89898bb
docs(api): say how legacy CLI modes are reported and which harness se…
charlesrhoward Sep 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion content/docs/mcp/tools.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,10 @@ A run prompt can invoke a skill without fetching it: write `$handle` in the
`prompt` of `mogplex_start_agent_run`. See
[Using Skills](/web/agents/using-skills).

`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. MCP tools aren't screened in `SAFE` and stay callable.

@mogplex mogplex Bot Sep 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

`mogplex_create_sandbox` consumes the existing launch event stream and returns
when the launch succeeds or fails. It does not create a separate status-polling
loop.
Expand Down Expand Up @@ -82,7 +86,7 @@ published graph.

| Tool | Scope | What it does |
| --- | --- | --- |
| `mogplex_start_agent_run` | `write` | Start a Codex or Claude Code run in a repo sandbox. |
| `mogplex_start_agent_run` | `write` | Start a Codex, Claude Code, or Mogplex agent run in a repo sandbox. |
| `mogplex_get_run` | `read` | Read current run state and metadata. |
| `mogplex_get_run_events` | `read` | Read append-only run events. |
| `mogplex_cancel_run` | `write` | Request cancellation of a one-off agent run, not a Flow job. |
Expand Down
37 changes: 32 additions & 5 deletions content/docs/reference/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ type MogplexApiError = {
| `GET` | [`/automations/{automationId}/runs`](#list-automation-runs) | `read` | List recent automation runs. |
| `GET` | [`/automations/{automationId}/runs/{runId}`](#read-automation-run-logs) | `read` | Read detailed automation run logs. |
| `POST` | [`/pr-reviews/rerun`](#rerun-a-pr-review) | `write` | Queue a fresh Mogplex PR review. |
| `POST` | [`/runs`](#start-a-run) | `write` | Start a Codex or Claude Code run. |
| `POST` | [`/runs`](#start-a-run) | `write` | Start a Codex, Claude Code, or Mogplex agent run. |
| `GET` | [`/runs/{runId}`](#get-a-run) | `read` | Read run state. |
| `GET` | [`/runs/{runId}/events`](#list-run-events) | `read` | Read structured run events. |
| `POST` | [`/runs/{runId}/cancel`](#cancel-a-run) | `write` | Cancel an active run. |
Expand Down Expand Up @@ -709,14 +709,20 @@ type MogplexApiRunDetail = {
sandboxRecordId: string | null;
sandboxId: string | null;
repoId: string;
harness: "codex" | "claude-code";
harness: "codex" | "claude-code" | "mogplex";
status: MogplexApiRunStatus;
branch: {
base: string;
working: string;
createBranch: boolean;
};
rootDirectory: string | null;
// The mode the request named. SAFE, AUTO, and YOLO are reported upper-cased
// (a request with "auto" reports "AUTO"). null when the request omitted mode
// (AUTO applies) and for a Mogplex-harness run, which takes no mode. Typed
// as a string because the Mogplex CLI's Codex cloud runs report the CLI's
// own run mode as sent (such as "single"), which runs as AUTO.
mode: string | null;
eventsUrl: string;
cancelUrl: string;
createdAt: string;
Expand All @@ -741,20 +747,41 @@ Request body:
type StartRunRequest = {
repoId: string;
prompt: string; // At most 100,000 characters.

@mogplex mogplex Bot Sep 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

harness?: "codex" | "claude-code"; // Default: codex.
harness?: "codex" | "claude-code" | "mogplex"; // Default: codex.
baseBranch?: string;
workingBranch?: string;
createBranch?: boolean;
rootDirectory?: string | null;
conversationId?: string;
workspaceSessionId?: string;
mode?: string;
mode?: "SAFE" | "AUTO" | "YOLO"; // Case-insensitive. Default: AUTO.
};
```

The response is `202 Accepted` with
`MogplexApiRunDetail & { replayed: boolean }` inside `data`.

`mode` sets what the harness may do in its sandbox:

- `SAFE`: the harness doesn't change the checkout. Claude Code plans instead
of editing, and Codex runs read-only. MCP tools are not screened, so a
connection or Mogplex tool that writes (a GitHub issue, a memory, a stdio
server with filesystem access) can still make changes.
- `AUTO`: the harness edits files and runs commands in the sandbox.
- `YOLO`: the harness runs without approval prompts. Claude Code still blocks
its deny-listed tools and commands, such as `curl`, `ssh`, and reading `.env`
files.

Any other value returns `400 BAD_REQUEST`, except the run modes released
Mogplex CLIs send for their cloud runs (such as `single`). Those runs use the
`codex` harness, and those modes are accepted for compatibility, stored as sent,
and run as `AUTO`. New callers should send one of the three values above.

`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

@mogplex mogplex Bot Sep 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

one unless `workingBranch` names a branch other than the base), and reports
`mode: null`.

When `createBranch` is true and `workingBranch` is omitted, Mogplex creates a
deterministic branch name from the idempotency key and request. If supplied,
the working branch must differ from the base branch.
Expand Down Expand Up @@ -872,7 +899,7 @@ https://mogplex.com/api/v1/mogplex/mcp
```

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.

@mogplex mogplex Bot Sep 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Request envelope:

Expand Down
Loading