Planning
How Sophon decomposes complex requests into a DAG of steps and runs them on Sophon Graph — in parallel, with checkpoints, retries, replanning, cancellation, and recovery when a plan stops.
When you ask Sophon something complex — "research three competitors, build a comparison spreadsheet, and email it to my team" — the agent doesn't just start typing. It plans: it breaks the work into steps, figures out which steps depend on which, and executes independent steps in parallel. If a step fails, it either retries with an alternative approach or cascades cleanly so other steps still run.
Planning is middleware #7 in the orchestration pipeline. Since v2.0.0, approved plans run on Sophon Graph by default.
When planning kicks in
Four modes, set per agent or per request:
| Mode | Behavior |
|---|---|
Auto (default) | Heuristic classifier scores the message; score ≥ 3 triggers planning |
LlmDecides | Fast-tier LLM is asked "is this complex?" (3-token answer, temp 0). Falls back to heuristic on error |
Always | Every request gets planned |
Never | Planning disabled; always flat agentic loop |
This Auto decides whether to make a plan at all. It is unrelated to the execution mode that decides how an approved plan runs — that one has exactly two values, Graph and Classic.
The heuristic
The heuristic classifier adds signal scores:
| Signal | Points |
|---|---|
| Message length > 100 chars | +1 |
| Contains conjunctions ("and then", "after that", "first", "then") | +2 (once) |
| Contains multi-step phrases ("steps", "plan", "sequence") | +2 (once) |
| Contains ≥ 2 action verbs (search, create, send, write, …) | +1 |
Score ≥ 3 means "complex, plan it."
Planning is skipped if the pipeline is already three levels deep. This prevents infinite plan-nesting when a plan step itself triggers planning.
The host-wide default is Sophon:AgentExecution:PlanningMode (default Auto, read live). Trusted per-message settings take precedence over it, and graph steps and heartbeats that are not allowed to plan always send Never. A CLI session bound to a workspace never plans automatically; there you ask for a plan with plan mode instead (see Plan mode in the coding agent).
Since v2.1.0 the heuristic matches phrases and verbs on whole words, so "authentication" no longer counts as "then". The weights and the threshold are unchanged.
What a plan looks like
A plan is a goal plus a DAG of steps. Each step carries an id, a description, the step ids it depends on, suggested tools, an estimated risk level, and optionally a model capability hint:
{
"id": "plan_abc123",
"goal": "Compare three competitors and email the team",
"steps": [
{ "id": "s1", "description": "Research Acme Corp",
"dependsOn": [], "toolHints": ["web.search", "browser.navigate"] },
{ "id": "s2", "description": "Research Globex",
"dependsOn": [], "toolHints": ["web.search", "browser.navigate"] },
{ "id": "s3", "description": "Research Initech",
"dependsOn": [], "toolHints": ["web.search", "browser.navigate"] },
{ "id": "s4", "description": "Build comparison spreadsheet",
"dependsOn": ["s1", "s2", "s3"], "toolHints": ["document.create"] },
{ "id": "s5", "description": "Email the team",
"dependsOn": ["s4"], "toolHints": ["gmail.send"],
"estimatedRisk": "Medium" }
]
}s1, s2, s3 have no dependencies → they run in parallel. s4 waits for all three research steps. s5 waits for the spreadsheet. And in an interactive session, the whole plan is shown for user approval before anything runs — see Approval below.
Execution
An approved plan is compiled into an immutable, versioned graph and handed to Sophon Graph, the durable execution engine. In each wave, every step whose dependencies are satisfied is dispatched together.
Checkpointing. Every state transition is written to the database as it happens, so a plan's progress outlives the process running it. If the Gateway restarts mid-run, completed steps are never re-run. A step that was in flight is a different matter: chat-plan steps are assumed to have side effects, so with the default recovery mode the run comes back Interrupted and waits for you to resume or cancel it — Sophon will not replay a half-finished email.send on its own. See Plan recovery for every way a plan can stop and how to pick it up again.
Isolated steps. Each step runs in its own child session with a small, clean context instead of one ever-growing transcript. Dependency outputs are wrapped and marked as untrusted before they reach the consuming step, and a step fed external content gets a lower auto-approve ceiling. Step sessions appear under their conversation in the Dashboard sidebar as Agent activity, and each step links to its own session while it runs — steps do not stream their tokens into the main chat.
Retries. On step failure, Sophon asks a fast-tier LLM for an alternative approach and retries. If there's no alternative, the step is marked failed.
Replanning. When a step keeps failing, Sophon revises the failed part of the plan into a new version, and the plan card shows a version badge. A revision that raises the plan's risk, reaches for a new kind of tool, or adds a step with side effects parks the run behind a durable approval gate — that gate survives a restart and waits hours rather than seconds. Frozen, completed steps are never re-gated.
Smart cascade. A failed step doesn't poison the whole plan. Steps that depended on it are marked Skipped, but unrelated steps continue. If the spreadsheet step above failed, the email step would be skipped but nothing upstream would be rolled back.
Budgets. A plan run carries a default cost cap and a token backstop, checked between waves. When a run goes over, no new steps are dispatched and the chat says which limit was hit. The caps are soft by design — steps already in flight are allowed to finish. Since v2.1.0 a budget stop is reported as a paused plan rather than a failed one, and you can continue it with a new budget. A run whose last wave crosses the cap now finishes with its answer; the stop happens only while work remains. The defaults are Sophon:GraphRuntime:MaxRunCostUsd = 2.00 and MaxRunTokens = 1,500,000.
Cancellation. Cancelling an active plan stops dispatching new steps; in-flight steps observe the cancellation token and stop at their next cancellation point. Pressing Stop, or sending a newer message that replaces the turn, cancels the plan. A graceful Gateway stop and the turn time limit pause it instead (see Plan recovery).
Status events
The engine emits events the UI can subscribe to:
plan_start,plan_complete,plan_failed,plan_interrupted,plan_updatedplan_step_start,plan_step_complete,plan_step_failed,plan_step_skipped,plan_step_retry
Clients (Dashboard, Mobile, CLI) subscribe via SignalR and render live progress — you see each step tick from pending → running → done, and a revised plan replaces the step list in place.
Since v2.1.0 a budget stop arrives as plan_interrupted (with costUsd and budgetUsd, plus tokensUsed and tokenBudget when the token cap is what tripped), not plan_failed. A cancelled plan's plan_failed event carries a cancelCause: UserStop, Superseded, HostShutdown, TurnTimeLimit or ContinuedAsRetry. Custom SignalR clients that treated every budget stop as a failure need updating; see SignalR events.
Graph or Classic
Execution mode is a choice, resolved per conversation:
| Surface | Scope |
|---|---|
| The execution-mode pill in the Dashboard composer | This conversation |
/mode graph|/mode classic|/mode default in the CLI | This session |
| Settings → Execution | Your personal default |
| Settings → Execution (admin panel) | The workspace default — and the ceiling |
Classic is the previous step-by-step engine: no checkpointing, no durable gates, and a crash mid-run ends that run. It remains the opt-out, both per conversation and host-wide via Sophon:GraphRuntime:Enabled=false. An admin turning Graph off for the workspace puts everyone on Classic regardless of their own preference.
Execution mode governs chat plans. A plan made inside a plan step or a sub-agent always runs Classic — a nested graph run would deadlock on the host's concurrency budget — and plans made by scheduled, heartbeat and webhook automations run on Graph like any other.
Approval
Whether a plan waits for approval is governed by the plan-approval mode (config Sophon:AgentExecution:PlanApproval, live-reloaded). The default for interactive sessions is Always: the user sees the full plan with all steps and can approve, reject, or edit (timeout: 10 minutes). In the Dashboard, Edit Plan opens a step editor on the plan card itself. A plan proposed in plan mode is edited on its card with Form and Markdown tabs. Unattended runs — heartbeat, cron, subagent, webhook — auto-proceed past the plan gate; a per-session override and a host default let you tune the behavior.
Plan approval is up-front: you approve once and aren't interrupted step by step. Three things can still ask for you mid-run:
- A plan revision that raises risk, adds a new tool family, or adds a side-effecting step — parked durably, as described above.
- A tool approval raised inside a running step, for a call above the step's auto-approve ceiling.
- A question a step asks you outright.
The last two are mirrored into your main conversation — Dashboard, Mobile, CLI, and the messaging channel the conversation came from — tagged with the step they came from, and the plan card flips that step to a waiting state. Unlike a revision gate, they wait in memory on a short timer: an unanswered approval is treated as rejected, an unanswered question tells the step to proceed on its best judgment, and a Gateway restart mid-wait fails that step attempt so the retry ladder picks it up again.
See Approval Gates for the risk model and thresholds.
Plan recovery
Since v2.1.0, a chat plan that stops partway tells you why it stopped and offers the action that fits. Whatever you choose, the steps that already finished are kept. This applies to chat plans that run on Graph. Classic plans and the graphs that agent.delegate builds are not covered. A paused delegation run, which v2.0 could resume, can now only be cancelled; Resume answers delegation_run.
Why a plan stopped
| What happened | Plan state | What you see | What fits |
|---|---|---|---|
| The Gateway crashed or restarted while a step with side effects was running | Paused | "Interrupted by a restart while a side-effecting step was running." | Resume |
| The Gateway was stopped gracefully | Paused | "Paused because Sophon restarted." | Resume |
The turn reached its time limit (Sophon:AgentExecution:MaxExecutionTime, 2 hours by default) | Paused | "Paused after reaching the turn time limit." | Resume |
| The run reached its cost or token cap | Paused | "Budget reached — $2.10 spent (limit $2.00)" or "Token budget reached — X of Y tokens" | Continue with a new budget |
| A step failed and the retries and replanning ran out | Failed, or completed with failed steps | The failed steps | Retry failed steps |
| You pressed Stop | Cancelled | "Plan stopped by you." | Retry failed steps |
| A newer message replaced the turn | Cancelled | "Plan cancelled — replaced by a newer message." | Retry failed steps |
The text for paused plans is the Dashboard's plan card; the text for stopped plans is the CLI's. The other surface words the same cause slightly differently.
The first two paused rows depend on Sophon:GraphRuntime:PauseOnStop (default true). With it on, a graceful stop parks running chat plans instead of cancelling them. The stop waits up to about 7 seconds (5 for plans to park, 2 to flush their events), which fits Docker's default 10-second stop grace period. The pause on a graceful stop also needs EnableDurableApprovals, which is on by default. With PauseOnStop off, a graceful stop and the turn time limit cancel the plan, as in v2.0.
Some runs are never paused: unattended runs (heartbeat, cron, webhook) and delegation runs still cancel on a stop. Every cancelled run records its cause.
Resume, retry, or continue
- Resume picks a paused plan up where it stopped, in the same run. A step that was running starts again from its beginning. Such an interruption usually does not use up one of the step's retries: up to
Sophon:GraphRuntime:InterruptedAttemptRefunds(default 2) interrupted attempts per step are not counted. Set it to0to count every interrupted attempt, as in v2.0. - Retry failed steps works on a plan that failed, was cancelled, or completed with failed or skipped steps. It starts a new run that keeps every completed step with its output and runs only the work that did not finish. The old run is never reopened.
- Continue with a new budget works on a plan stopped by its budget. It also starts a new run that keeps the completed steps, with a fresh budget window under the same caps. The stopped run is closed and links to its continuation. To resume the original run in place instead, an admin first raises the cap.
Each plan gets at most one continuation. Pressing the button twice returns the continuation that already exists rather than starting a second one. A step that a security check blocked stays blocked, and a step you stopped yourself is not run again.
Retrying runs steps again, and some of them may have side effects such as sending an email. The Dashboard's preview lists the steps that will run again, the steps that are kept and the steps that stay blocked, and it warns you when a step that will run again has side effects. Read it before you confirm.
Where to do it
Dashboard. The plan card shows why the plan stopped. A paused plan has Resume and Cancel; a budget stop also has Continue with a new budget. A failed, stopped or partly failed plan has Retry failed steps. Both retry actions open the preview dialog first. After a page reload, the Dashboard rebuilds plan cards from the newest 400 events and the session's runs; after a reconnect, it re-reads the session's runs.
CLI chat. When a plan stops, the CLI prints one line that names the next command:
Plan paused because Sophon restarted. /retry graphrun_1a2b3c4d resumes it./retry [runId] is one command for all three actions: it resumes a paused plan, retries a failed or stopped one, or continues a budget stop. With no run id it uses the session's newest plan. With no plan running, /plan shows the session's newest plan, including one from before you reopened the session. In the full-screen overlay, press r to run /retry.
CLI, outside the chat. The sophon plans command group, which had only cancel in v2.0, now covers the whole lifecycle:
sophon plans list --status Interrupted --limit 50
sophon plans show graphrun_1a2b
sophon plans resume graphrun_1a2b
sophon plans retry graphrun_1a2b
sophon plans cancel graphrun_1a2b # durable cancel; also stops a paused planshow, resume, retry and cancel take a run id, a unique prefix of one, or a plan id. plans list defaults to 20 rows (at most 200) and accepts --session <id>. sophon plans resume on a plan that is not paused tells you the right command instead, for example sophon plans retry <runId>. Every failure exits with code 1. See CLI commands.
Mobile. A paused plan shows a static tracker: "Paused — resume or continue it from the Dashboard or the CLI." The app has no Resume or Retry buttons yet. A stopped plan reads "Cancelled" rather than "Failed", and the push notification for a stopped plan now opens that plan's chat.
Ask the agent. Say "retry the plan" in the chat. The agent uses the built-in plan.recover tool, which works on the chat's newest plan or on a run id you give it. It always raises a Critical-risk approval card that lists the action, the steps that will run again, the kept and blocked steps, and the side-effect warning. Auto-approve never covers it, and the card cannot be edited. The tool only works in an interactive top-level chat; sub-agents, plan steps, scheduled runs, webhooks, workflows and MCP clients cannot use it.
REST API
| Endpoint | What it does |
|---|---|
GET /api/graph-runs | Lists runs. New in v2.1.0: sessionId and kind=plan (chat plans only). status and limit (default 50, 1–200) work as before. Each summary includes retryOfRunId. |
GET /api/graph-runs/{id} | The run, plus continuationRunId, emitPlanEvents and a retry block that says whether the run can be retried and what would happen. |
POST /api/graph-runs/{id}/resume | Resumes a paused run. Returns 202 { id, status: "resuming" }. |
POST /api/graph-runs/{id}/retry | New. Retry failed steps or continue with a new budget, whichever fits. No body. |
POST /api/graph-runs/{id}/cancel | Cancels a run, including a paused one. Recorded as a stop by you. |
A retry returns 202 Accepted with Location: /api/graph-runs/<newId> and { "id": "<newId>", "planId": "…", "retryOfRunId": "<id>", "created": true }. Calling it again returns 200 with "created": false and the continuation that already exists.
curl -X POST -H "Authorization: Bearer $TOKEN" \
http://localhost:5000/api/graph-runs/graphrun_1a2b3c4d/retryThe retry block on GET /api/graph-runs/{id} looks like this for a budget stop:
"retry": {
"eligible": true, "reason": null, "message": "", "kind": "budget",
"rerunNodeIds": ["b", "c"], "partialContextNodeIds": [], "carriedNodeIds": ["a"],
"blockedNodeIds": [], "baselineVersion": null, "effectful": false,
"budget": { "spentUsd": 2.10, "capUsd": 2.00, "tokens": 412000, "tokenCap": 1500000 }
}kind is "retry", "budget" or null. budget is null unless kind is "budget".
Refusals are 409 with { "error": "<code>", "message": "<sentence>" }. The codes include use_resume (the plan is paused; resume it instead), run_active, session_busy (another plan in the same session is running), nothing_to_retry, only_blocked_steps, delegation_run, plan_unavailable, retry_disabled, graph_runtime_disabled and, for resume, not_interrupted and budget_exceeded. A host that is stopping answers 503 with host_stopping. A run that does not exist or is not yours returns 404 with no body. A retry of a plan that already has a continuation is not refused: it returns that continuation, and the retry block shows "reason": "already_retried". See the REST API reference.
Breaking in v2.1.0. Every /api/graph-runs refusal now has the shape { error: <stable code>, message }. In v2.0 the sentence was in error. Cancelling a run that already finished returns already_terminal. Update scripts that read error as text.
Settings
{
"Sophon": {
"GraphRuntime": {
"PauseOnStop": true,
"EnableRunRetry": true,
"InterruptedAttemptRefunds": 2
}
}
}These are the defaults. EnableRunRetry: false refuses every retry with retry_disabled and leaves resume and cancel alone; it is read on every request. Sophon:GraphRuntime:Enabled: false also turns off PauseOnStop and EnableRunRetry.
Limits
- Mobile can show a paused plan but cannot resume or retry it.
- Only one Gateway replica per database is supported, and the
session_busycheck is best-effort. - Do not downgrade to v2.0 while any plan is paused by a graceful stop or the turn time limit: v2.0 cannot read those states. Set
PauseOnStoptofalsefirst, resume or cancel the paused plans, and checksophon plans list --status Interruptedbefore you downgrade. See Upgrading to v2.1.0. - Upgrade the Dashboard and Mobile together with the Gateway. Older clients expect a budget stop as
plan_failed.
Plan mode in the coding agent
Everything above is about plans Sophon makes on its own when a request looks complex. The CLI coding agent adds a second way to plan, which you turn on yourself: plan mode. Enter it with /permissions plan (or Shift+Tab in the full-screen and classic CLI, or the mode chip in the Dashboard). In plan mode only read-only tool calls run, for the agent and its sub-agents; a write is refused at the call. The agent proposes a plan with the plan.propose tool, and from the plan card you can run it in the chat, run it as a graph, edit it, send it back with feedback (up to Sophon:AgentExecution:PlanMaxRevisions times per turn, default 3), or reject it. Only the session owner on an elevated connection can approve a card that ends plan mode. On Personal that means the CLI, and the Personal Dashboard can only reject it; on Pro and Enterprise the owner's Dashboard can approve it.
Plan mode is not a network control: web search and fetch, GET HTTP requests and agent.delegate still run. See The coding agent for the details.
Model hints
A plan step can declare capability requirements:
{
"id": "s4",
"description": "Analyze the results and write a two-paragraph executive summary",
"modelHint": { "requiresReasoning": true }
}The Capability Routing middleware picks a provider/model that advertises reasoning support for that step. If no provider qualifies, the step errors rather than silently falling back to an unqualified model.
Dynamic tool chains
Related to planning is the tool.create_chain meta-tool, which lets the LLM compose existing tools into a new tool at runtime:
{
"name": "research_and_save",
"description": "Search, scrape, and save to memory",
"steps": [
{ "toolName": "web.search", "arguments": { "query": "{{input.topic}}" } },
{ "toolName": "browser.navigate", "arguments": { "url": "{{previous_result.top_url}}" } },
{ "toolName": "memory.write", "arguments": { "content": "{{previous_result.text}}" } }
]
}Chain risk is the max of all constituent tool risks, and every referenced tool is validated before the chain is registered.
Configuration
{
"Sophon": {
"AgentExecution": {
"PlanningMode": "Auto",
"PlanMaxSteps": 20,
"PlanMaxRevisions": 3
},
"GraphRuntime": {
"Enabled": true,
"PauseOnStop": true,
"EnableRunRetry": true
}
}
}Sophon:GraphRuntime:Enabled is the host-wide master switch for graph execution; setting it to false restores the previous step-by-step engine for everyone. The planning mode is per-agent; set it in the agent's config or via sophon agents edit <id> --planning-mode Auto|LlmDecides|Always|Never.
Where to go next
- Sophon Graph — the durable execution engine approved plans run on
- Orchestration Pipeline — how planning fits into the broader request flow
- Approval Gates — the risk model and how plans, revisions, and tool calls are gated
- The coding agent — plan mode, the todo checklist, and sub-agents in the CLI
- CLI commands —
sophon plansand the rest of the command reference