Mohamed BoudraandGitHub
ccb4e444ed
* docs(hub): name the Hub tools in workflow prompts
Every Hub workflow example now tells the agent which tool to call:
hub.reply for the user-facing response, hub.finish_execution to
complete the step and record structured output. Granting a capability
through allow_outputs makes the tool available; it does not make an
agent use it, and an agent that is not told answers in its own
transcript and leaves the step to its idle timeout. Explicit
instructions are what worked against real agents.
Classifier and other intermediate steps name hub.finish_execution
alone, so the docs do not imply every step must reply.
Drops the github.reply allow_outputs blocks from the GitHub examples.
The GitHub provider registers no output capabilities, so that
declaration never materializes a tool; those agents comment through
their scoped GH_TOKEN with gh, which the reference and trigger pages
already said. The read-only answer branch has no network authority for
that, so it only finishes.
Also quotes the "Request: ${{ paseo.prompt }}" prompt block in the
reference, which was invalid YAML as written.
* docs(hub): wrap triggering input in its own prompt block
Every Hub YAML example now ends its prompt with the raw triggering
message wrapped in <user-prompt> tags, as a separate block after the
workflow instructions. The agent can see where your instructions stop
and the request starts, which matters most on the steps that read
external Slack, Discord, and GitHub text.
The first workflow explains the convention in two sentences and points
at Hub security for the controls that actually limit an agent. Tags
label the input; they are not containment, and the docs do not claim
otherwise.
Replaces the earlier quoting fix in the prompt-blocks reference: the
message now lives in a block scalar, so the colon needs no quoting.
* docs: base worktree examples on origin/main
Every branch-off example now passes a remote-tracking ref. Paseo
fetches remote refs in the background, so origin/main is current while
the local main is whatever was last pulled, and base resolution tries
refs/heads first: an unqualified main silently branches off stale
history. The gotcha is explained once, next to the first branch-off
example in the worktrees guide; the other pages just use the ref, and
the Hub environment reference links there.
Also points the safety-gate classifier at the structured-output
section, which shows the output wrapper the finish call takes.
* docs(hub): configure Codex read-only through provider options
Hub examples described a read-only Codex step as mode: read-only. That
Paseo mode preset pairs the read-only sandbox with approval_policy
on-request, so an unattended Hub step stops to ask a question nobody is
there to answer. It is also not one of the modes the Codex provider
advertises.
Every read-only step now uses the provider-native passthrough proven by
the real-provider evidence in #3025: approval_policy never,
sandbox_mode read-only, web_search disabled. The security guide already
used this block; the workflow guide, examples, and reference now agree
with it, and the reference says plainly that a Paseo mode ID is a
separate surface from these options.
mode: full-access is unchanged. It maps to approval_policy never, so it
does not stall an unattended step.
* docs(hub): show a classifier choosing the repository and the model
Both routing jobs were only documented as caller-supplied inputs, so
there was no example of the thing people actually want: one read-only
classifier that reads the request, picks the repository it belongs to
and the model it needs, and hands both to a worker. Replaces the
caller-only model example, which the new one covers through its
override values.
The two axes are not symmetric and the example says so. A model is a
value, so values.selected_model goes straight into agent.model. An
environment cannot come from an expression at all: the compiler accepts
a literal name or paseo.inputs.<name> and nothing else, so each
repository needs its own environment and its own conditional step. One
classifier, exactly one worker.
Corrects the routing section, which listed environment among the fields
an agent output may select. It never could.
Also puts a blank line between adjacent steps and environments in the
deadline and repository-routing examples, and bases the daemon worktree
example on origin/main, which the earlier sweep missed.
* fix(website): keep development requests local
Canonical host redirects were applied to LAN-addressed development traffic, including inspector WebSockets. The redirected socket retained the Vite port and caused the development proxy to terminate when the public host timed out.
* docs(hub): order the workflow scenarios from simple to hard
The Hub pages were arranged by the shape of the configuration schema
rather than by what a reader is trying to do, which showed up three
ways: the overview opened on the storage hierarchy, workflow
configurations were split between workflows.md and a separate examples
page, and the examples that existed started with the hardest one.
workflows.md is now a ladder. One Slack trigger answering in a thread
stays inline as the first workflow, and nine further scenarios sit
under it as collapsible blocks, each a complete configuration adding
one idea to the one above: full access, repeated replies, a GitHub
trigger, two ordered steps, a typed input, two triggers, a classifier
choosing a model, a classifier choosing a repository, and last the
override composed with ??. configuration/examples.md is removed and its
configurations live there now.
Two claims in the old material were wrong and are corrected. Nothing
carries between steps except a declared output, so the planning
scenario passes its plan through output.schema instead of telling the
second agent to follow a plan it cannot see, and a worktree environment
creates a worktree per execution rather than sharing one. GH_TOKEN
authenticates the gh CLI but does not configure git, so the pages no
longer imply a step can push without a commit identity and credential
helper on the daemon host.
The overview drops the organization/connections/daemons/projects tree,
which concepts.md already owns, in favour of the smallest configuration
that does something. Hosting is now a link from the product pages
rather than a section in them.
* docs(hub): make GitHub access an explicit step grant
GitHub authority gets its own page. A step holds a token only when it
declares a github block — connection, repositories, permissions,
duration — and Hub supplies GH_TOKEN plus environment-only git
configuration, revoked when the step ends. No credential is ever
implied by the trigger source.
Rewrites the issue-to-pull-request scenario onto the block, repoints
the trigger, reference, FAQ, and concepts pages, and sweeps the Hub
pages for announcing sentences and compressed paragraphs.
* docs(hub): lighten dense reference prose
Restructure paragraph walls into short paragraphs, lists, and code
blocks: logout behavior in daemons, deploy paths and precedence in
configuration, install limits and dispatch fields in the API page,
required outputs and partial resolution in the reference, and the
policy translation and secrets guidance in security. Fixes two
remaining trigger-derived credential claims in triggers/index.
* fix(nix): update npm dependency hash
* docs(hub): document shared prompts and authority defaults
24 KiB
title, description, nav, order, category
| title | description | nav | order | category |
|---|---|---|---|---|
| Hub workflows | Learn how Hub turns a provider event into one or more ordered agent steps, from a single reply to classifier-driven routing. | Workflows | 64 | Hub |
Hub workflows
A workflow is the work Hub performs after a trigger matches an event. You describe it in .paseo/hub.yml, next to the environments where your agents run.
Slack mention → Hub trigger → workflow step → Paseo daemon → agent
Your first workflow
One Slack trigger and one agent that answers in the thread:
environments:
- name: development
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
triggers:
- name: slack-help
on: slack.mention
max_runtime: 2h
filters:
workspace: T01234567
channels: [C01234567]
from_users: [U01234567]
steps:
- id: answer
environment: development
max_runtime: 30m
idle_timeout: 5m
agent:
provider: codex
options:
approval_policy: never
sandbox_mode: read-only
web_search: disabled
prompt:
- text: |
Help with this request.
Call hub.reply to send your response to the originating conversation.
Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
allow_outputs:
- type: slack.reply
Mention the bot in the configured channel:
@Paseo how do I run the project locally?
Hub removes the mention and gives the agent how do I run the project locally? as ${{ paseo.prompt }}. The agent answers through hub.reply, which posts in the thread, and Project → Activity records the event, the step, the outcome, and the reply.
agent.options passes Codex's own settings through unchanged: no approval prompts, a read-only sandbox, no web search. Nobody is watching an unattended step, so one that stops to ask an approval question goes nowhere. Provider-native controls has the equivalent block for each provider.
The last prompt block wraps the triggering message in <user-prompt> tags and keeps it as its own prompt item, so the agent can tell the request apart from your instructions. Tags are a formatting convention; Hub security covers the allowlists, provider policy, and output authority that decide what an agent may do with the request.
For GitHub, Discord, and manual runs, only the trigger and invocation change. The steps work the same way. See Triggers for provider matching.
Tell the agent which tool to call
Hub attaches its own tools to every step, and the prompt has to name the one you want. An agent that is not told can end its turn with the answer only in its own transcript: nothing delivered, no output recorded, and the step left to its idle_timeout.
hub.replysends a user-facing response to the conversation that triggered the workflow. It exists only when the step'sallow_outputsgrants a matching capability.hub.finish_executionmarks the step complete and records the structured result when the step declares anoutputschema.
A step that answers a person names both, as the first workflow does:
Call hub.reply to send your response to the originating conversation.
Call hub.finish_execution when the step is complete.
A step that only feeds a later step names hub.finish_execution alone. Most classifiers never reply.
Share prompt text between steps
Put shared instructions in .paseo/partials/base.md:
Follow the repository's conventions.
Keep the work focused on the request.
Include the file in each step that needs it:
steps:
- id: review
prompt:
- include: base.md
- text: Review the request and call hub.finish_execution when complete.
- id: implement
prompt:
- include: base.md
- text: Implement the request and call hub.finish_execution when complete.
See prompt partials for path resolution, deployment, and validation.
Scenarios
:::example[Make a change instead of answering]
mode: full-access lets the agent edit files and run commands. The environment gets a worktree, so the work happens on its own branch instead of your checkout.
environments:
- name: development
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
worktree:
mode: branch-off
newBranch: hub/work
base: origin/main
triggers:
- name: slack-work
on: slack.mention
max_runtime: 2h
filters:
workspace: T01234567
channels: [C01234567]
from_users: [U01234567]
steps:
- id: work
environment: development
max_runtime: 90m
idle_timeout: 10m
agent:
provider: codex
mode: full-access
prompt:
- text: |
Make the change, verify it, and report what you did.
Call hub.reply to send your response to the originating conversation.
Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
allow_outputs:
- type: slack.reply
Base the worktree on origin/main rather than main. Git worktrees explains why, along with setup hooks and scripts.
:::
:::example[Report progress while working]
max is how many times a step may use a capability, and it defaults to 1. Raise it and tell the agent to send updates as it goes.
environments:
- name: development
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
worktree:
mode: branch-off
newBranch: hub/work
base: origin/main
triggers:
- name: slack-work
on: slack.mention
max_runtime: 2h
filters:
workspace: T01234567
channels: [C01234567]
from_users: [U01234567]
steps:
- id: work
environment: development
max_runtime: 90m
idle_timeout: 10m
agent:
provider: codex
mode: full-access
prompt:
- text: |
Make the change, verify it, and report what you did.
Call hub.reply when you start, when something surprising happens,
and when you finish.
Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
allow_outputs:
- type: slack.reply
max: 5
Set required: true when a step must send at least one reply before it can finish successfully. See output capabilities.
:::
:::example[Turn an issue into a pull request]
A github block on the step grants the authority: a token scoped to the listed repositories and permissions, plus a git setup that commits and pushes with it. See GitHub access.
environments:
- name: development
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
worktree:
mode: branch-off
newBranch: hub/work
base: origin/main
triggers:
- name: issue-to-pr
on: github.issues
max_runtime: 2h
filters:
repo: example/project
from_users: [maintainer]
steps:
- id: implement
environment: development
max_runtime: 90m
idle_timeout: 10m
auto_archive: true
github:
connection: example-github
repositories:
- example/project
permissions:
contents: write
pull_requests: write
agent:
provider: codex
mode: full-access
prompt:
- text: |
Implement what the issue asks for, verify it, commit, push the
branch, and open a pull request with `gh pr create`.
Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
GitHub sends an issues event for every issue action, so opening, editing, or closing an issue as a listed user each starts a run. ${{ paseo.prompt }} carries the issue title and body.
The trigger and the block are independent. The trigger only starts the run; without the block the agent has no token, GitHub-triggered or not. hub.reply covers Slack and Discord, so here the deliverable is the pull request and hub.finish_execution completes the step. auto_archive archives the agent when the step ends.
:::
:::example[Plan first, then implement] Steps run in order, and each one gets its own agent, limits, and authority. Here a read-only step posts a plan and a full-access step carries it out.
environments:
- name: triage
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
- name: development
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
worktree:
mode: branch-off
newBranch: hub/work
base: origin/main
triggers:
- name: slack-work
on: slack.mention
max_runtime: 3h
filters:
workspace: T01234567
channels: [C01234567]
from_users: [U01234567]
steps:
- id: plan
environment: triage
max_runtime: 10m
idle_timeout: 2m
agent:
provider: codex
options:
approval_policy: never
sandbox_mode: read-only
web_search: disabled
prompt:
- text: |
Read the code and write the approach you would take. Change nothing.
Call hub.finish_execution with the approach as the structured result.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
output:
schema:
type: object
additionalProperties: false
required: [plan]
properties:
plan:
type: string
- id: implement
environment: development
max_runtime: 90m
idle_timeout: 10m
agent:
provider: codex
mode: full-access
prompt:
- text: |
Carry out this approach, verify it, and report the result.
${{ steps.plan.outputs.plan }}
Call hub.reply to send your response to the originating conversation.
Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
allow_outputs:
- type: slack.reply
Each step is a separate agent execution with its own prompt, and nothing carries over on its own. The second agent never sees the first agent's transcript. The only thing that crosses is what the first step declared under output and the second step interpolated, which is why the plan is a schema field here rather than a sentence in a reply.
Environments do not carry over either. A worktree environment creates a worktree for each execution that uses it, so two steps sharing one worktree environment get two branches rather than one shared working directory. The planning step runs in triage, which has no worktree, because it only reads.
An output that a prompt interpolates does not need finite choices. That requirement applies to agent.provider, agent.model, agent.mode, and environment, which is covered further down.
:::
:::example[Let the caller choose]
A declared input is a typed value the caller supplies as a leading key=value token. Hub validates it before any agent starts.
environments:
- name: development
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
triggers:
- name: slack-help
on: slack.mention
max_runtime: 2h
filters:
workspace: T01234567
channels: [C01234567]
from_users: [U01234567]
inputs:
model:
type: string
default: gpt-5.5
choices: [gpt-5.5, gpt-5.4-mini]
steps:
- id: answer
environment: development
max_runtime: 30m
idle_timeout: 5m
agent:
provider: codex
model: ${{ paseo.inputs.model }}
options:
approval_policy: never
sandbox_mode: read-only
web_search: disabled
prompt:
- text: |
Help with this request.
Call hub.reply to send your response to the originating conversation.
Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
allow_outputs:
- type: slack.reply
@Paseo model=gpt-5.4-mini how do I run the project locally?
Hub reads leading key=value tokens that match declared inputs. gpt-5.4-mini becomes ${{ paseo.inputs.model }}, and the rest is the prompt. The first token that is not a declared input starts the prompt, so ordinary text is never consumed.
An input that selects a provider, model, or mode needs choices. A prompt cannot supply authority. Types, defaults, and rejected values are in the hub.yml reference.
:::
:::example[Send two repositories to two triggers]
When two routes should stay separate, give each its own trigger and match on the supplied input with filters.inputs.
environments:
- name: project
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
- name: paseo
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/paseo
triggers:
- name: project-request
on: slack.mention
max_runtime: 2h
filters:
workspace: T01234567
from_users: [U01234567]
inputs: { repo: project }
inputs:
repo:
type: string
choices: [project, paseo]
steps:
- id: project-work
environment: project
max_runtime: 90m
idle_timeout: 10m
agent:
provider: codex
mode: full-access
prompt:
- text: |
Do the work in this repository.
Call hub.reply to send your response to the originating conversation.
Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
allow_outputs:
- type: slack.reply
max: 5
- name: paseo-request
on: slack.mention
max_runtime: 2h
filters:
workspace: T01234567
from_users: [U01234567]
inputs: { repo: paseo }
inputs:
repo:
type: string
choices: [project, paseo]
steps:
- id: paseo-work
environment: paseo
max_runtime: 90m
idle_timeout: 10m
agent:
provider: codex
mode: full-access
prompt:
- text: |
Do the work in this repository.
Call hub.reply to send your response to the originating conversation.
Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
allow_outputs:
- type: slack.reply
max: 5
One event can match several triggers and all of them run; the input filters are what keep these two routes exclusive.
@Paseo repo=paseo investigate the failed sync
:::
:::example[Let the agent choose the model]
A structured output is a JSON value an agent returns when it finishes. Declare its schema with an enum, and a later step can read the decision.
environments:
- name: development
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
triggers:
- name: slack-help
on: slack.mention
max_runtime: 2h
filters:
workspace: T01234567
channels: [C01234567]
from_users: [U01234567]
steps:
- id: classify
environment: development
max_runtime: 2m
idle_timeout: 30s
agent:
provider: codex
options:
approval_policy: never
sandbox_mode: read-only
web_search: disabled
prompt:
- text: |
Pick gpt-5.4-mini for a small question and gpt-5.5 for real work.
Call hub.finish_execution with the choice as the structured result.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
output:
schema:
type: object
additionalProperties: false
required: [model]
properties:
model:
enum: [gpt-5.5, gpt-5.4-mini]
- id: answer
environment: development
max_runtime: 30m
idle_timeout: 5m
agent:
provider: codex
model: ${{ steps.classify.outputs.model }}
mode: full-access
prompt:
- text: |
Handle this request.
Call hub.reply to send your response to the originating conversation.
Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
allow_outputs:
- type: slack.reply
The classifier calls the tool with its result under output:
hub.finish_execution({ output: { model: "gpt-5.4-mini" } })
Hub validates that object against the schema. An invalid one returns an MCP error and the same agent can correct it and call again. A valid one completes the step and makes the value available as ${{ steps.classify.outputs.model }}.
The enum is what allows an agent-produced value to select a model at all. An output that selects a provider, model, or mode has to prove its choices are finite, through an enum or a const.
:::
:::example[Let the agent choose the repository]
A model is a value, so it goes straight into agent.model. A repository is a configured environment with its own cwd, and environment takes a literal name or ${{ paseo.inputs.<name> }} and nothing else. Give each repository its own environment and its own conditional step.
environments:
- name: triage
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
- name: project
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
worktree:
mode: branch-off
newBranch: hub/work
base: origin/main
- name: paseo
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/paseo
worktree:
mode: branch-off
newBranch: hub/work
base: origin/main
triggers:
- name: slack-work
on: slack.mention
max_runtime: 3h
filters:
workspace: T01234567
channels: [C01234567]
from_users: [U01234567]
steps:
- id: classify
environment: triage
max_runtime: 2m
idle_timeout: 30s
agent:
provider: codex
options:
approval_policy: never
sandbox_mode: read-only
web_search: disabled
prompt:
- text: |
Decide which repository this request belongs to.
Call hub.finish_execution with the choice as the structured result.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
output:
schema:
type: object
additionalProperties: false
required: [repo]
properties:
repo:
enum: [project, paseo]
- id: project-work
if: ${{ steps.classify.outputs.repo == 'project' }}
environment: project
max_runtime: 90m
idle_timeout: 10m
agent:
provider: codex
mode: full-access
prompt:
- text: |
Do the work in this repository.
Call hub.reply to send your response to the originating conversation.
Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
allow_outputs:
- type: slack.reply
max: 5
- id: paseo-work
if: ${{ steps.classify.outputs.repo == 'paseo' }}
environment: paseo
max_runtime: 90m
idle_timeout: 10m
agent:
provider: codex
mode: full-access
prompt:
- text: |
Do the work in this repository.
Call hub.reply to send your response to the originating conversation.
Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
allow_outputs:
- type: slack.reply
max: 5
Steps run in order, and Hub skips a step whose if is false. The two conditions here cannot both be true, so the configuration lists a step per repository while a run only ever executes one of them.
The classifier runs in triage, which has no worktree, because a read-only classification does not need a branch. The same shape scopes credentials: a github block on each worker grants authority for its own repository, and the classifier holds none. See GitHub access.
:::
:::example[Accept a caller override with a classifier fallback]
values binds an expression under its own name, and ?? takes the first side that is present. A caller who already knows the answer supplies it, and the classifier covers everyone else.
values:
selected_repo: ${{ paseo.inputs.repo ?? steps.classify.outputs.repo }}
Declare repo as an input with choices, keep the classifier's enum output, and give the classifier a condition so it only runs when it is needed:
inputs:
repo:
type: string
choices: [project, paseo]
steps:
- id: classify
if: ${{ paseo.inputs.repo == null }}
# unchanged from the scenario above
- id: project-work
if: ${{ values.selected_repo == 'project' }}
# unchanged from the scenario above
- id: paseo-work
if: ${{ values.selected_repo == 'paseo' }}
# unchanged from the scenario above
Both sides of a ?? used for authority have to be finite on their own: choices on the input, an enum in the output schema. A composed value can select a provider, model, or mode. It cannot select an environment, which is why the branches above still test values.selected_repo rather than feeding it to environment.
The namespaces stay separate:
${{ paseo.inputs.repo }}— deterministic caller evidence.${{ steps.classify.outputs.repo }}— structured agent evidence.${{ values.selected_repo }}— a composed value. :::
Choosing between a caller input and a classifier
| Use | When |
|---|---|
| Deterministic input | The caller knows the answer and should control the route. |
| Classifier output | The route depends on the request and the caller should not have to label it. |
| Both | Give experienced callers an explicit override and use classification as the fallback. |
A read-only classifier is also a way to keep authority away from the step that reads untrusted text. It reduces exposure without being a boundary. Hub security covers the trust boundary, provider-native controls, and what to check before pointing a workflow at a public repository.
Next
The hub.yml reference covers every field, expression, and limit, including prompt partials for text shared between steps, deadlines, and provider invocation.
Then return to Configuration to connect the file to a project, or Activity to inspect a run.