Chat policy

The Chat policy decides whether devboxes answers in Chat, which model it uses, and which operations it may run. Owners and admins set it with chat.configure-policy, as Turn on Chat shows. chat.policy reads it.

Fields

Field	What it holds
`enabled`	Whether devboxes answers in Chat.
`candidates`	The model selection for Chat: 1 to 20 candidates, as in Choose models.
`outputTokenLimit`	The longest answer a model may write, from 1 to 100,000 tokens.
`operations`	Optional. The operations that Chat may use. Without it, Chat may use every operation that it can call, including operations that devboxes adds later.
`version`	In the result only. Saving the policy increments it.

Chat then uses only the listed operations, except that a tracker issue's conversation can always read its own issue, and a reply can always open the summarized lines of its own conversation and of Organization memory with chat.zoom, and erase messages of its own conversation with chat.erase-messages when a person asks. An operation that devboxes adds later stays unavailable until you add it to the list. To let Chat use every operation again, save the policy without operations. chat.policy shows operations only for a policy that lists them.

A list must include the operations that your Blueprints use: publication.commit for a Blueprint with a publish node, and the operations that the Blueprints' capabilities name. When the policy is on and allows sessions.dispatch or sessions.continue, the command fails with CHAT_POLICY_INCOMPLETE if a Blueprint that the Project of a Chat Channel uses needs an operation that the policy leaves out. A Blueprint without bindings serves every Project. The error names those Blueprints and the operations to add. Routing a Chat Channel to a Project with chat.configure-channel or issues.configure runs the same check. blueprints.bind and blueprints.commit don't fail for this reason, because Members can still start the Blueprint. When a Project of a Chat Channel can use the Blueprint and the policy cannot start it, their result has a warning that names the Blueprint and the operations to add. When Chat can't start work for this reason, it tells the person in plain words what Chat isn't allowed to do, and that an owner or admin of the named Organization can allow it.

What the operations let Chat do

Operations	What people in a channel of the Project can do
`sessions.dispatch`, `sessions.continue`	Start tasks and give them more work.
`sessions.input`	Pass a message to a task's running work.
`sessions.cancel`	Cancel a task whose latest work their own request in Chat started.
`sessions.handoff`	Move a task into their conversation, after a confirmation when that changes who can read it.
`images.inspect`	Ask what a Project's workspace contains.
`images.configure`	Change the packages and services of a Project's workspace. A change starts a build.
`projects.configure-merging`	Owners and admins: let devboxes merge a Project's pull requests once a Review approves them.
`sessions.hold-merge`	Ask devboxes not to merge a task's work, or to let them see it first.
`repositories.merge`, `repositories.review`, `repositories.checks`	Owners and admins: ask devboxes to merge a pull request, even with open Review findings.
`issues.configure`	Owners and admins: connect a Project to an issue tracker.
`issues.read`	Read the issues of the Project's tracker, with their comments.
`issues.write`	Take an issue from Chat.
`chat.add-waiting-work`, `chat.resolve-waiting-work`, `sessions.dispatch`	Start work after other work finishes.
`schedules.create`, `schedules.list`, `schedules.pause`, `schedules.resume`, `schedules.run`, `schedules.delete`	Run a request on a schedule in the thread, list the thread's Schedules, and pause, resume, run, or delete those they set up.
`sessions.artifacts`, `chat.post-artifact`	Get the media that their work produced, as Images and files describes.
`memory.list`, `memory.create`, `memory.update`, `memory.erase`	Read Organization memory, and change it from a thread of a channel that everyone in the workspace can read.

A request that needs a role, such as an owner's or an admin's, works only from a linked chat account.

Pull request reads

Read	Operation
List the open pull requests of a repository.	`repositories.pulls`
Read a pull request: its title, description, author, changed files with their diffs, review threads, and comments.	`repositories.review`
Read the checks of a pull request.	`repositories.checks`

Blueprint operations

Operation	What devboxes can do for a member who asks
`blueprints.read`	Read the steps of a Blueprint, to show them or to change them.
`blueprints.create`	Set up a new Blueprint as a draft.
`blueprints.draft`	Start a change to a Blueprint as a draft.
`blueprints.replace-draft`	Write the steps into a draft.
`blueprints.place-group`	Copy a group of steps from another Blueprint into a draft.
`blueprints.discard`	Delete a draft that nobody needs.
`blueprints.commit`	Commit a draft that a member asked for. A version that reaches a sensitive integration awaits an owner's approval.
`blueprints.bind`	Limit a Blueprint to a Project, or lift that limit.
`blueprints.archive`	Retire a Blueprint.

A policy without operations allows all of them. devboxes refuses a person whose chat account isn't linked, and sends them a private link to link it. A direct conversation refuses these operations with CHANNEL_REQUIRED.

Allowed without the policy

In a direct message, whatever the Chat policy allows, Chat can store and change the person's preferences with people.remember and people.correct, unless preferences are turned off, and delete one with people.forget. There devboxes sees the person's own preferences, so it can tell them what they stored and change or forget the one they mean. Anywhere else Chat never lists anyone's preferences. People list their own with people.preferences.

Errors

The policy can list only operations that Chat can call. The command fails with CHAT_OPERATION_UNAVAILABLE and names the operations that Chat can't call, such as repositories.catalog, which only a Member can call. A policy saved before devboxes checked this keeps working, and Chat doesn't use those operations.

Chat refuses a model account on a provider that it cannot run, such as Amazon Bedrock or SAP AI Core, with CHAT_PROVIDER_UNSUPPORTED. To check the provider, the command reads the model catalog. When devboxes has no copy of the catalog yet and models.dev returns an error, the command fails with 503 MODEL_CATALOG_UNAVAILABLE. Try it again later.

CHAT_POLICY_INCOMPLETE names the Blueprints that the Projects of a Chat Channel use and the operations that the policy leaves out.