Blueprints and approvals

A Blueprint describes a kind of work as a graph of steps.

How a task runs the graph

A node runs once every node before it has finished and at least one of its incoming edges matches. An edge's when is succeeded, failed, or completed. A node is skipped when none of its incoming edges matches. When a node fails and has no failed or completed edge, the task fails right away. Agent nodes run one at a time and never alongside command nodes. The publish node runs alone.

A command node runs until its command exits, and a service node waits until its ready check passes or the service exits. Neither has a time limit, so stop a task that hangs with sessions.cancel.

When a service exits after its ready check passed, sessions.events shows a message that names the service, its exit code or signal, and the last 16 KiB of its output, with secret values redacted. The agent gets the same message during its running turn, or with the next agent node's instructions. When no agent node follows, the message starts no turn.

To retry, add the steps explicitly: a failed test leads to a fix node and a second test node, and both test nodes lead to the publish node.

An agent node ends when the agent reports it complete: what it did, anything it did not expect, and a one-line summary. devboxes ends the agent's turn at that report, before the agent's next model request. It ends the turn the same way when the agent reports that something the node requires is missing, and the node fails with the agent's reason. When a person's message reaches the turn after the agent's last answer, the turn stays open until the agent ends it, also when a notice such as a background command's end follows the message. When the agent ends its turn without that report, devboxes gives it the node's instructions again and asks it to complete the node. The next agent node sees the report in the results of the nodes before it. Before the publish node runs, or at the end of the graph when no agent node ran before it or the graph has no publish node, the agent gets the whole task and its reports. It checks its work, corrects what it needs to and amends the affected reports, and then reports the goal achieved. A task whose agent node failed skips this review. Background commands that the agent starts keep running after its turn ends and wake the agent when they end. devboxes stops the ones that still run when the agent reports the goal achieved or the task ends.

sessions.inspect shows the state of a task's nodes, and under steps the agent's reports.

Publishing

The publish node is the only way to push the agent's changes. Without one, the agent can change files but cannot push them. It commits the changes left uncommitted with the message of the workspace's latest commit, which an agent or a command node can make, or with the Session's title when nothing was committed. Then it pushes the new commits to the task's branch, and the pull request lists them all. The commits keep the author and committer that the agent's Git configuration names. Nothing is published when a commit message contains a Secret value, when someone else pushed to the branch after the task started, when the teammate's pull request that the task works on is no longer open, or when GitHub refuses them, for example through branch protection or push protection. A push can replace the branch's history when the agent amended or rebased commits that were already published, including on a teammate's pull request branch, unless the branch's protection or a ruleset forbids force pushes. When branch protection or a ruleset keeps devboxes from pushing to the pull request branch of a task that works on a teammate's pull request, devboxes publishes to the task's own branch and opens a pull request into the teammate's branch instead. On GitHub, publishing also opens a pull request for the task's branch when none is open, titled with the latest commit message's first line and described by the rest. When GitHub refuses, for example because the connection may not open pull requests, the commits stay published. When the publish node opened or found the pull request of the task's branch, agent nodes after it get its number, so a node that writes its description or comments on it needs no lookup.

When a task pauses at its model account's usage limit before its publish node runs, the publish node runs right away, whatever its incoming edges. It commits the changes left uncommitted with the message Pause at the <provider> usage limit: checkpoint of <Session title> and pushes every new commit to the task's branch as above, but opens no pull request. When the task has nothing new to commit or push, the publish node is skipped. The publish node of the Session's next task opens the pull request, titled with that task's latest commit message as above. When that task adds no commit, the pull request takes the Session's title.

Sensitive integrations and approvals

An owner marks the integrations that need their approval as sensitive: a Blueprint operation, such as repositories.github-write, a secret, or a connected MCP server. repositories.github-write, which edits, closes, and comments on pull requests, is sensitive until an owner marks it otherwise. A publish node pushes the branch and opens the pull request with publication.commit, which an owner can mark too. Work reaches an integration when its Blueprint binds the operation, or when the secret is one that the Project's tasks receive.

Work that reaches a sensitive integration starts only with a version that an owner approved. A version that an owner commits from a draft they wrote last is approved. Any other version waits until an owner approves it. A task does not fall back to an earlier version. Versions that bind repositories.github-write and were committed before approvals existed count as approved, because only owners and admins could commit them.

Outside a task, only an owner calls a sensitive operation, for example to comment on a pull request: from the CLI or the API, or in Chat from a chat account linked to them. Members reach it through a task whose version an owner approved. A task calls a sensitive operation only when its version is approved, even one an owner marked while the task ran. A secret marked sensitive applies to tasks dispatched afterwards, and a task already dispatched keeps the secrets it was given.

Blueprints that Chat sets up

Members who linked their chat account can ask devboxes in a Chat channel to set up a new way of working or change one, in their own words. For example: "For checks and investigations, don't open pull requests." devboxes sets it up in the same reply as a new Blueprint for that kind of work, so other work keeps its Blueprint. It changes an existing Blueprint only when you name it, or when that Blueprint serves only that kind of work, and then says which work the change affects. It tells you what it set up, or what still stops the Blueprint from being used, such as an owner's approval. Ask again to change it. devboxes commits a Blueprint change only when a member asks for it, and it passes their words to blueprints.commit, which checks that a person wrote them in a message the reply answers. When a conversation only suggests a change, such as a complaint about a result, devboxes writes the change as a draft, says what it would change, and asks an owner to approve it. devboxes commits the draft once an owner approves it or a member explicitly asks for that change, and either of them can also commit it with blueprints.commit. Members see drafts in blueprints.list, from Chat too. devboxes archives a Blueprint only when a member asks. It refuses a person whose chat account isn't linked, and a direct conversation refuses with CHANNEL_REQUIRED. The Chat policy must allow the Blueprint operations.

A Blueprint that Chat sets up serves every Project until someone binds it to a Project. When devboxes in Chat starts work, it chooses the Blueprint whose description fits the work best among those the Project can use, and never asks you to pick one. When several fit about equally well, it asks you one question about the work you want, and starts the one that your answer fits. A bundle picked on Start a task narrows that choice to its Blueprints, and when none of them fits, devboxes asks you. So start a Blueprint's description with the work it fits. A task started from the CLI that names no Blueprint uses the Project's bound one, as Start a task describes.

For a Blueprint that Chat sets up, blueprints.list shows the account of the person who asked as createdBy.