jb/paseo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Rework Hub workflow docs around explicit delivery and GitHub authority (#3086)

Browse Source 
* 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
This commit is contained in:
Mohamed Boudra
2026-08-09 16:59:00 +02:00
committed by GitHub
parent b0a7d493aa
commit ccb4e444ed
37 changed files with 1337 additions and 508 deletions
Download Patch File Download Diff File Expand all files Collapse all files
public-docs/hub/configuration/examples.md
-236
View File
@@ -1,236 +0,0 @@
---
title: Hub examples
description: Copyable Hub workflow configurations for typed routing, classification, direct answers, implementations, and provider replies.
nav: Examples
order: 70
category: Hub
---
# Hub examples
These examples use the durable step syntax. Replace the daemon, paths, provider identifiers, and provider filters with resources in your organization. The shared workflow page explains the contract behind each pattern.
## Model and provider selection
Use finite choices when caller input selects an agent provider or model.
```yaml
environments:
- name: development
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
triggers:
- name: selectable-agent
on: manual.run
max_runtime: 2h
filters:
from_users: [automation]
inputs:
provider:
type: string
default: codex
choices: [codex, claude]
model:
type: string
default: standard
choices: [standard, fast]
steps:
- id: work
environment: development
max_runtime: 90m
idle_timeout: 10m
agent:
provider: ${{ paseo.inputs.provider }}
model: ${{ paseo.inputs.model }}
mode: full-access
prompt:
- text: ${{ paseo.prompt }}
```
Invoke it with `provider=claude model=fast investigate the sync`. An undeclared leading key stops header parsing and becomes prompt text.
## Repository routing
Use a declared input plus `filters.inputs` when separate triggers should own separate repositories or projects.
```yaml
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: ${{ paseo.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: ${{ paseo.prompt }}
allow_outputs:
- type: slack.reply
max: 5
```
The same event can match multiple triggers, so the input filters make these routes exclusive.
## Safety gate and direct answer
For a request that may either be answered or implemented, let a read-only classifier choose a finite branch. Supplying `kind=answer` or `kind=implementation` skips classification.
```yaml
environments:
- name: development
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
triggers:
- name: request
on: github.issue_comment
max_runtime: 2h
filters:
repo: example/project
contains: "@paseo"
from_users: [maintainer]
inputs:
kind:
type: string
choices: [answer, implementation]
steps:
- id: classify
if: ${{ paseo.inputs.kind == null }}
environment: development
max_runtime: 2m
idle_timeout: 30s
agent:
provider: codex
mode: read-only
prompt:
- text: Classify this request as answer or implementation.
- text: ${{ paseo.prompt }}
output:
schema:
type: object
additionalProperties: false
required: [kind]
properties:
kind:
enum: [answer, implementation]
- id: answer
if: ${{ paseo.inputs.kind == 'answer' || steps.classify.outputs.kind == 'answer' }}
environment: development
max_runtime: 10m
idle_timeout: 2m
agent:
provider: codex
mode: read-only
prompt:
- text: Answer the request. Do not change files.
- text: ${{ paseo.prompt }}
- id: implementation
if: ${{ paseo.inputs.kind == 'implementation' || steps.classify.outputs.kind == 'implementation' }}
environment: development
max_runtime: 90m
idle_timeout: 10m
agent:
provider: codex
mode: full-access
prompt:
- text: Implement the request, verify it, and report the result.
- text: ${{ paseo.prompt }}
allow_outputs:
- type: github.reply
max: 5
```
The answer and implementation conditions cannot both be true for one classification. The workflow ends after the answer step because there is no later matching step.
## PR progress and final updates
Keep progress and final updates on the implementation step. The step can use up to five replies while it works, then finish normally.
```yaml
environments:
- name: development
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/project
triggers:
- name: pr-work
on: github.pull_request_review_comment
max_runtime: 2h
filters:
repo: example/project
contains: "@paseo"
from_users: [maintainer]
steps:
- id: implement-review
environment: development
max_runtime: 90m
idle_timeout: 10m
auto_archive: true
agent:
provider: codex
mode: full-access
prompt:
- text: |
Address the review request.
Request: ${{ paseo.prompt }}
allow_outputs:
- type: github.reply
max: 5
```
For Slack and Discord, use `slack.reply` or `discord.reply` instead. GitHub-triggered agents also receive the scoped GitHub credential for the triggering repository, so the agent can use `gh` for repository updates.
See [Hub workflows](/docs/hub/workflows) for partials, deadlines, structured output retry, and provider invocation details.
public-docs/hub/configuration/hub-yml.md
+34 -7
View File
@@ -2,7 +2,7 @@
title: hub.yml reference
description: The authored Hub configuration: environments, triggers, typed inputs, workflow steps, routing, and prompt partials.
nav: hub.yml reference
order: 69
order: 71
category: Hub
---
@@ -34,7 +34,11 @@ triggers:
provider: codex
mode: full-access
prompt:
- text: ${{ paseo.prompt }}
- text: Call hub.finish_execution when the step is complete.
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
```
`project` is an optional bare project slug. The deploy CLI uses it to choose the target project when `-p, --project` is absent. The flag takes precedence over this metadata without rewriting the YAML. `project` is not available to triggers, expressions, or agents.
@@ -50,7 +54,7 @@ triggers:
| `image` | fly/docker | Image name. |
| `worktree` | no | `branch-off`, `checkout-branch`, or `checkout-pr` target. |
The `worktree` object is part of the environment. Its fields are exact authored names: `newBranch` and optional `base` for `branch-off`, `branch` for `checkout-branch`, and positive integer `prNumber` for `checkout-pr`.
The `worktree` object is part of the environment. Its fields are exact authored names: `newBranch` and optional `base` for `branch-off`, `branch` for `checkout-branch`, and positive integer `prNumber` for `checkout-pr`. Give `base` a remote-tracking ref such as `origin/main`; see [Git worktrees](/docs/worktrees#create-a-worktree-backed-workspace).
## Triggers
@@ -106,22 +110,31 @@ The grammar supports paths, JSON literals, parentheses, `!`, `==`, `!=`, `&&`, `
| `agent` | yes | `provider`, optional `model`, `mode`, `thinkingOptionId`, and provider-native `options`. |
| `prompt` | yes | Non-empty list of `text` and GitHub-only `include` blocks. |
| `if` | no | Expression deciding whether this ordered step runs. |
| `output` | no | `{ schema: <JSON Schema> }` for structured `finish_execution`. |
| `env` | no | Environment variables populated from connection values. See [GitHub access](/docs/hub/github#other-integrations). |
| `output` | no | `{ schema: <JSON Schema> }` for the structured result the agent passes to `hub.finish_execution`. |
| `allow_outputs` | no | Registered output capabilities such as `slack.reply` or `discord.reply`, each with optional `max` and `required`. |
| `auto_archive` | no | Archives the step's agent when it ends. |
| `github` | no | Scoped GitHub token and git setup for this step. See [GitHub access](/docs/hub/github). |
Prompt blocks are objects, not a scalar prompt:
```yaml
prompt:
- text: Request: ${{ paseo.prompt }}
- include: developer.md
- text: |
<user-prompt>
${{ paseo.prompt }}
</user-prompt>
```
Keep the triggering message in its own final block, wrapped in `<user-prompt>` tags, as [the first workflow](/docs/hub/workflows#your-first-workflow) does.
Use `${{ paseo.prompt }}`, `${{ paseo.inputs.* }}`, `${{ steps.*.outputs.* }}`, and `${{ values.* }}` in prompts, conditions, and agent selection fields. Provider event payloads are not part of this workflow expression namespace; provider adapters put the normalized request into the prompt and preserve the raw event as evidence.
`agent.options` carries JSON-safe options using the selected provider's native names and nesting. Paseo validates them with that provider's strict schema before starting the session. See [Hub security](/docs/hub/security) for the trust boundary and copyable provider examples.
`mode` names a Paseo agent mode ID, which is a separate surface from these options. Some modes keep the provider's interactive approval flow, and that stalls an unattended step, so set the provider's own approval and sandbox settings in `options` instead.
#### Output capabilities
`allow_outputs` separates permission from obligation. `max` limits how many times a capability may be emitted and defaults to `1`. Set `required: true` when the step must emit that capability at least once before it can finish successfully:
@@ -133,11 +146,24 @@ allow_outputs:
required: true
```
Hub counts an actual capability emission; ordinary assistant text does not satisfy a required output. A required declaration must resolve to a registered, available Hub capability for that execution context, or dispatch rejects the step with an actionable configuration error. If delivery fails, the attempt is retryable; if the agent tries to finish first, Hub keeps the execution recoverable and names the concrete output tool before retrying `finish_execution`. A required output must have an effective `max` of at least `1`, or activation rejects the configuration. Omitting `required` preserves optional-output behavior and does not change the agent's permission mode. GitHub-triggered agents reply with their scoped `GH_TOKEN` (for example, through `gh issue comment`) rather than a Hub `github.reply` tool.
`required: true` means the step must actually emit the capability. Assistant text does not count.
- A required output must resolve to a registered, available capability for the execution, or dispatch rejects the step.
- A required output needs an effective `max` of at least `1`, or activation rejects the configuration.
- Failed delivery is retryable. An agent that tries to finish first is told the concrete output tool to call, then `hub.finish_execution` is retried.
Omitting `required` keeps the output optional. GitHub has no reply capability; a step acts through the `gh` CLI with the token its [`github` block](/docs/hub/github) grants.
A declaration grants the tool. The step's prompt still has to tell the agent to call `hub.reply`, and to call `hub.finish_execution` when it is done. See [Tell the agent which tool to call](/docs/hub/workflows#tell-the-agent-which-tool-to-call).
## Prompt partials
`include` paths are relative to `.paseo/partials/`. For GitHub configuration, Hub reads them at the exact configuration commit and stores the resolved content and SHA-256 hash in the immutable revision. For `paseo hub deploy`, the CLI reads the referenced files from the local project root and sends them in the optional `partials` bundle; the bundle path omits the `.paseo/partials/` prefix. Missing files, unsafe paths, symlinks, submodules, directories, duplicate or unexpected bundle entries, and nested includes are rejected. Manual configurations cannot use repository partials.
`include` paths are relative to `.paseo/partials/`.
- GitHub configuration: Hub reads each file at the exact configuration commit and stores the resolved content and SHA-256 hash in the immutable revision.
- `paseo hub deploy`: the CLI reads the referenced files from the local project root and sends them in the optional `partials` bundle. The bundle path omits the `.paseo/partials/` prefix.
- Missing files, unsafe paths, symlinks, submodules, directories, duplicate or unexpected bundle entries, and nested includes are rejected.
- Manual configurations cannot use repository partials.
## Deadlines
@@ -149,6 +175,7 @@ steps:
- id: classify
max_runtime: 2m
idle_timeout: 30s
- id: implement
max_runtime: 90m
idle_timeout: 10m
public-docs/hub/configuration/index.md
+20 -5
View File
@@ -2,7 +2,7 @@
title: Hub configuration
description: Where a project's configuration comes from, how GitHub sync works, and how revisions activate and roll back.
nav: Configuration
order: 68
order: 70
category: Hub
---
@@ -38,13 +38,28 @@ paseo hub deploy --dry-run
paseo hub deploy
```
The default path is exactly `.paseo/hub.yml` relative to the current directory. The CLI does not search parent directories or alternate filenames. Use `paseo hub deploy path/to/config.yml` for another file. The bundle root remains the current directory, so partials are always read from `.paseo/partials/` under that directory. `-p, --project <slug>` overrides the file's `project` value without changing the YAML sent to Hub.
Deploy reads exactly `.paseo/hub.yml` in the current directory; it does not search parent directories. Partials are read from `.paseo/partials/` under the same directory.
For each prompt `include`, the CLI sends one `{ path, content }` entry whose path is relative to `.paseo/partials/`. It sends only files referenced by the main YAML; nested include-looking text inside a partial is not scanned. Missing, unsafe, duplicate, unreadable, non-file, or oversized inputs fail locally before the Hub request. A configuration with only inline prompt blocks sends no `partials` field.
- `paseo hub deploy path/to/config.yml` deploys another file. The bundle root stays the current directory.
- `-p, --project <slug>` overrides the file's `project` value without changing the YAML sent to Hub.
- `--dry-run` sends the identical resolved YAML, project slug, and partial bundle to Hub's validator. Nothing is recorded or activated.
`--dry-run` sends the identical resolved YAML, project slug, and prompt-partial bundle to `POST /api/v1/configurations/validate`. Hub performs the same compilation and resource resolution as installation but records and activates nothing.
For each prompt `include`, the CLI sends one `{ path, content }` entry whose path is relative to `.paseo/partials/`. Only files referenced by the main YAML are sent; include-looking text inside a partial is not scanned. Missing, unsafe, duplicate, unreadable, non-file, or oversized inputs fail locally, and a configuration with only inline prompt blocks sends no `partials` field.
Origin precedence is `--hub`, `PASEO_HUB_URL`, the active stored login, then `https://hub.paseo.sh`. Credential precedence is `--api-key`, `PASEO_HUB_API_KEY`, then an exact-origin stored login. API keys passed by flag or environment are not stored. A stored credential is organization-scoped and is never reused for a different Hub origin. Deploy and dry-run report the normalized destination before sending anything and include it in structured results.
Origin precedence:
1. `--hub`
2. `PASEO_HUB_URL`
3. The active stored login
4. `https://hub.paseo.sh`
Credential precedence:
1. `--api-key`
2. `PASEO_HUB_API_KEY`
3. An exact-origin stored login
Keys passed by flag or environment are not stored, and a stored credential is never reused for a different Hub origin. Deploy and dry-run print the normalized destination before sending anything.
## Sync