update_workflow
Replace every field of a workflow, hooks and event_prompts included.
writesidempotentMCP toolWorkflow
Agents already launched keep the context they started with.
Calling it#
curl -X POST http://127.0.0.1:8787/komrad.workflow.v1.WorkflowService/UpdateWorkflow \
-H 'Content-Type: application/json' \
-d '{
"id": "<id>",
"name": "<name>"
}'komrad rpc update-workflow \
--id '<uuid>' \
--name '<string>'{
"name": "update_workflow",
"arguments": {
"id": "<id>",
"name": "<name>"
}
}Offered by the komrad MCP server to orchestrator agents.
Request#
UpdateWorkflowRequest#
| Field | Type | Description |
|---|---|---|
id | uuid* | The workflow to update, by id. |
name | string* at most 200 characters must not contain control characters | The workflow's name. |
context | string at most 50000 characters | The workflow's context. Agents already launched keep theirs. |
cwd | string at most 4096 characters must be blank, absolute, or start with ~ | The directory agents launched from now on start in. |
worktree | WorktreeConfig | Whether the workflow's tasks get worktrees, and how komrad creates them. Turning worktrees off applies to existing tasks too, so deleting one leaves its worktree on disk. |
hooks | WorkflowHook[] at most 50 items | The workflow's hooks, in full. |
event_prompts | WorkflowEventPrompt[] at most 50 items | The workflow's event prompts, in full. |
writer | RoleSettings | What the workflow launches its writers with from now on. |
reviewer | ReviewerSettings | What the workflow launches its reviewers with and holds them to from now on. |
orchestrator | OrchestratorSettings | What the workflow launches its orchestrator with and holds it to from now on. |
Response#
Empty#
No fields.
Types#
WorktreeConfig#
WorktreeConfig is whether a workflow's tasks get worktrees, and how komrad creates them.
| Field | Type | Description |
|---|---|---|
enabled | bool | Whether each task gets a worktree. False runs agents in the workflow's directory. |
base_branch | string at most 255 characters must not contain shell metacharacters | The workflow's base branch. Empty on create reads the branch from the repository. |
copy_paths | string[] at most 50 items each at most 255 characters each must be a relative path without a leading / or ~ or a .. segment | The untracked files to copy into each new worktree, such as ones a build needs. |
symlink_paths | string[] at most 50 items each at most 255 characters each must be a relative path without a leading / or ~ or a .. segment | The files to link into each new worktree instead of copying, such as large shared ones. |
diff_exclude | string[] at most 50 items each not empty each at most 255 characters each must be a relative path without a leading / or ~ or a .. segment | The paths or globs left out of a task's diff and line counts, such as generated output. |
dir | string at most 4096 characters must be blank, absolute, or start with ~ | The directory new worktrees are created in. Empty uses the directory all workflows share. |
setup_command | string at most 1000 characters must not contain control characters | The shell command run in each worktree before its writer starts and before every resume of the writer, such as one that installs the repository's tools. Keep it quick when nothing is missing. Empty runs nothing. |
shrink_paths | string[] at most 50 items each at most 255 characters each must be a gitignore pattern that does not start with ! or # and has no control characters | The gitignore patterns, relative to the worktree, such as |
WorkflowHook#
WorkflowHook is a hook that runs at one moment in the life of a workflow's task or agent.
| Field | Type | Description |
|---|---|---|
event | Moment* one of agent.pre-launch agent.post-launch agent.pre-resume agent.post-resume agent.pre-archive agent.post-archive agent.pre-restore agent.post-restore agent.pre-delete agent.post-delete task.pre-open task.post-archive task.pre-delete | The moment the hook runs at. |
script | string* at most 255 characters must be blank or a file name without a slash, a leading dot or control characters | The hook's script, by file name in the hooks directory. |
WorkflowEventPrompt#
WorkflowEventPrompt is what a workflow's agents are told to do when komrad mails them an event.
RoleSettings#
RoleSettings is what a workflow launches every agent in one role with. An empty or unset setting uses the one komrad's config sets for the role.
| Field | Type | Description |
|---|---|---|
harness | string at most 40 characters matching ^[a-z0-9-]*$ | The harness the role's agents run. Empty uses the config's harness for the role, then komrad's default. |
flags | string at most 500 characters must not contain shell metacharacters | The flags the role's agents start with. Empty uses the config's flags for the role when |
context | string at most 50000 characters | The text added to the system prompt of the role's agents only, after the workflow's context. Each agent keeps the context it was launched with. |
auto_compaction | int32 at least 0 | The conversation size in tokens the role's agents are held under. 0 leaves the CLI's own default, and unset uses the config's value for the role. |
ReviewerSettings#
ReviewerSettings is what a workflow launches its reviewers with and holds them to.
| Field | Type | Description |
|---|---|---|
role | RoleSettings | The settings every role has. |
max_per_task | int32 at least 1 | How many live reviewers one of the workflow's tasks may hold at once. Unset uses the config's value. |
archive_on_approval | bool | Whether komrad archives a reviewer once it releases an approval. Unset uses the config's value. |
OrchestratorSettings#
OrchestratorSettings is what a workflow launches its orchestrator with and holds it to.
| Field | Type | Description |
|---|---|---|
role | RoleSettings | The settings every role has. |
max_tasks | int32 at least 0 | How many live tasks the orchestrator may have started at once. 0 sets no cap of its own, and unset uses the config's value. |
Moment#
Moment is a point in the life of an agent or task at which komrad runs a script.
| Value | Description |
|---|---|
agent.provision | runs the provisioner before komrad creates an agent's directory |
agent.resume | reruns the provisioner before komrad resumes an agent |
agent.deprovision | runs the deprovisioner as komrad releases an agent's directory |
agent.pre-launch | runs in the agent's directory before its pane opens, and a failure abandons the create |
agent.post-launch | runs once the agent's pane opens |
agent.pre-resume | runs in the agent's directory before a dormant agent's pane opens, and a failure refuses the resume |
agent.post-resume | runs once a dormant agent is back in a pane |
agent.pre-archive | runs while the agent is still running, and a failure refuses the archive |
agent.post-archive | runs in the agent's directory after komrad closes its pane and archives it |
agent.pre-restore | runs before an archived agent's row comes back, and a failure refuses the restore |
agent.post-restore | runs when an archived agent's row comes back |
agent.pre-delete | runs in the agent's directory as komrad deletes it, before komrad releases the worktree |
agent.post-delete | runs once the agent and its worktree are gone |
task.pre-open | runs before a task's first live agent opens its pane, and a failure abandons the create or restore |
task.post-archive | runs after komrad archives a task's last live agent, and the task with it |
task.pre-delete | runs as komrad deletes a task, before it releases the worktree, and a failure keeps the task |
Event#
Event is something komrad tells an agent about through mail.
| Value | Description |
|---|---|
pull_request.checks_failing_running | some checks on the head failed while others still run |
pull_request.checks_failing | checks on the head failed and the run has finished |
pull_request.checks_passing | checks on the head passed and the forge would merge it |
pull_request.changes_requested | the forge review decision asks for changes |
pull_request.approved | the forge review decision is approved |
pull_request.conflicting | the branch conflicts with its base |
pull_request.behind | the branch is behind its base |
pull_request.merged | the pull request was merged |
pull_request.closed | the pull request was closed unmerged |
pull_request.auto_merge_on | the forge will merge it once its checks and reviews pass |
worktree.rebased | the worktree was rebased and its commits replayed |
worktree.landed | the work was already in the base, so the branch moved onto it |
worktree.rebase_conflicted | a rebase stopped on conflicts |
document.written_by_person | a person wrote or edited the agent's document |
review.approved | a reviewer approved the agent's work |
review.changes_requested | a reviewer asked for changes |
review.commented | a reviewer released comments without a verdict either way |
review.commented_by_person | a person commented on the agent's work |
review.forge_commented | a comment from the pull request on the forge was released |
review.answered | the agent under review answered in a thread, read by its reviewer |
pull_request.head_stale | the forge hasn't moved the pull request onto the branch's newest commit |
task.quiet | every agent on a task went quiet with the task neither parked nor waiting on komrad |
worktree.shrunk | komrad deleted build output from the worktree while its task was archived |