start_orchestrator

Bring a workflow's orchestrator back with a pane to talk to, starting the one that workflow has never had.

AgentwritesidempotentMCP tool

An orchestrator is the agent drawn on the workflow's own row rather than a row of its own, and it hands work out across that workflow rather than writing any itself. This returns whichever orchestrator the workflow already has, taking it out of the archive and resuming its conversation as far as either is needed, and launches a fresh one only when the workflow has never had one hold a conversation at all. An orchestrator already running comes back as it stands rather than being started twice, so this is safe to call again. A workflow that does not exist is refused as not_found.

Calling it#

curl -X POST http://127.0.0.1:8787/agent.v1.AgentService/StartOrchestrator \
  -H 'Content-Type: application/json' \
  -d '{
  "workflowId": "<workflowId>"
}'

komrad rpc start-orchestrator \
  --workflow-id <string>

{
  "name": "start_orchestrator",
  "arguments": {
    "workflowId": "<workflowId>"
  }
}

Offered by the komrad MCP server to orchestrator agents.

Request#

StartOrchestratorRequest#

Field Type Description

Field	Type	Description
`workflowId`	string	The workflow whose orchestrator to bring back, or to start if it has never had one. required

workflowId

string

The workflow whose orchestrator to bring back, or to start if it has never had one.

required

Response#

StartOrchestratorResponse#

Field	Type	Description
`agent`	Agent	The orchestrator, with a pane to talk to.

Types#

Agent#

Field	Type	Description
`id`	string	The handle every other call names this agent by, and what mail is addressed to.
`name`	string	What the panel lists it as, which is also its tmux window name at launch.
`cwd`	string	The directory it is running in, its own worktree when the workflow provisions one.
`flags`	string	The command-line flags its CLI was started with.
`prompt`	string	The whole briefing it was launched with.
`paneId`	string	The tmux pane its CLI is running in, which is what capture-pane reads.
`state`	AgentState	What the panel last decided it was doing, read off the tail of its pane.
`sessionId`	string	The CLI's own conversation id, which is the handle a resume needs.
`harness`	string	Which CLI it runs, such as claude or codex.
`workflowId`	string	Which workflow it is filed under, whose context it took at launch.
`createdAt`	string	When it was launched, in RFC 3339.
`archivedAt`	string	When it was hidden from the panel, unset while it is live.
`scheduleId`	string	The schedule that launched it, unset for an agent a person or another agent spawned.
`alive`	bool	Whether its pane is still there, which a dormant agent's is not.
`hidden`	bool	Whether the panel draws a row for it, which changes nothing about the agent itself.
`metadata`	list of AgentMetadata	Facts it has recorded about its own work, such as the ticket it is implementing.
`idempotencyKey`	string	The key a retry of its create carried, which is what answers a repeat with this agent.
`spawnedByAgentId`	string	Which agent called create, unset for one a person spawned.
`parentAgentId`	string	The agent this one is attached to, where spawned_by_agent_id is only who called create.
`branch`	string	The git branch its worktree is on, unset for an agent that provisions none.
`repositoryUrl`	string	The canonical web address of the repository its checkout pushes to, such as https://github.com/harrisoncramer/komrad, unset when the checkout is gone or its origin is not a forge.
`headSha`	string	The commit its checkout has checked out, unset when the checkout is gone or git cannot read it.
`worktreeRemoved`	bool	Whether its checkout has been taken away, which leaves the record and the transcript.
`sequenceInProgress`	bool	Whether a merge, a rebase or a cherry-pick is part-way through its checkout, waiting on somebody to settle it.
`failedRun`	bool	Whether a script komrad fired for the agent failed and nobody has looked at it since.
`failedRunLog`	int32	The run log that failure was written to, which is the run the panel opens on.
`stateChangedAt`	string	When the state above last moved, in RFC 3339.
`reportedReason`	string	What the agent's own CLI last reported it was doing, which annotates the state the pane decided rather than replacing it.
`role`	AgentRole	What the agent was launched to do, which decides the half of the review briefing it is sent.
`promptTruncated`	bool	Whether prompt holds only its opening, which a summary listing returns so that a page of agents does not carry every briefing they were launched with.
`treeStanding`	ReviewTreeStanding	Where the agent's worktree stood when last measured against the round tree_standing_sha names.
`treeStandingSha`	string	The snapshot of the round tree_standing was measured against, empty before any measurement.
`movedSinceRound`	string	The snapshot of its newest round while its worktree no longer hashes to it, empty otherwise.
`heldAt`	string	When a person stopped this agent and took its worktree, empty while nobody is holding it.

AgentMetadata#

Field	Type	Description
`key`	string	What the fact is filed under, such as pr or branch.
`value`	string	The fact as the panel shows it, which is why a URL belongs here whole.

AgentState#

AgentState is what the panel last decided an agent was doing, read off the tail of its pane.

Value	Description
`AGENT_STATE_IDLE`	The pane is at rest with nothing typed.
`AGENT_STATE_THINKING`	The CLI is working on a turn.
`AGENT_STATE_WAITING`	The CLI is blocked on a human answering a selection.
`AGENT_STATE_SETTING_UP`	The agent is being launched and has no pane to read yet.
`AGENT_STATE_FAILED_TO_CREATE`	The launch failed, which retry_agent is for.
`AGENT_STATE_FAILED_TO_CLEANUP`	A delete failed to take the worktree down, and the reason is on the row.
`AGENT_STATE_UNCERTAIN`	The pane could be read but its tail decided nothing.

AgentRole#

AgentRole is what an agent was launched to do.

Value	Description
`AGENT_ROLE_IMPLEMENTER`	An agent that lands work on a branch of its own.
`AGENT_ROLE_REVIEWER`	A child that reads another agent's work and gives a review.
`AGENT_ROLE_ORCHESTRATOR`	The agent drawn on a workflow's own row that hands work out.

ReviewTreeStanding#

ReviewTreeStanding is where an agent's worktree stands against the round its last verdict was given on.

Value	Description
`REVIEW_TREE_STANDING_MOVED`	The worktree differs from the round and the base does not hold the round.
`REVIEW_TREE_STANDING_LANDED`	The base holds the round whole and the worktree carries nothing beyond the base.
`REVIEW_TREE_STANDING_LANDED_MOVED`	The base holds the round whole and the worktree carries new work on top of the base.