docs(hub): document required output contracts (#2948)
* docs(hub): document required output contracts * docs(hub): link faq to output contract * docs(hub): document materializable required outputs Explain that required declarations resolve through registered capabilities, failed deliveries can be retried, and command-line repository comments use the scoped credential path.
This commit is contained in:
Mohamed Boudra
@@ -93,18 +93,18 @@ The grammar supports paths, JSON literals, parentheses, `!`, `==`, `!=`, `&&`, `
|
||||
|
||||
### Steps
|
||||
|
||||
| Field | Required | Notes |
|
||||
| --------------- | -------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | yes | Lowercase step identifier, unique within the trigger. |
|
||||
| `environment` | yes | Environment name or a finite input expression resolving to one. |
|
||||
| `max_runtime` | yes | Positive step hard limit, up to 24h. |
|
||||
| `idle_timeout` | yes | Positive idle limit, no longer than the step hard limit. |
|
||||
| `agent` | yes | `provider`, optional `model`, `mode`, and `thinkingOptionId`. |
|
||||
| `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`. |
|
||||
| `allow_outputs` | no | Reply capabilities such as `slack.reply`, `discord.reply`, or `github.reply`, each with optional `max`. |
|
||||
| `auto_archive` | no | Archives the step's agent when it ends. |
|
||||
| Field | Required | Notes |
|
||||
| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | yes | Lowercase step identifier, unique within the trigger. |
|
||||
| `environment` | yes | Environment name or a finite input expression resolving to one. |
|
||||
| `max_runtime` | yes | Positive step hard limit, up to 24h. |
|
||||
| `idle_timeout` | yes | Positive idle limit, no longer than the step hard limit. |
|
||||
| `agent` | yes | `provider`, optional `model`, `mode`, and `thinkingOptionId`. |
|
||||
| `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`. |
|
||||
| `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. |
|
||||
|
||||
Prompt blocks are objects, not a scalar prompt:
|
||||
|
||||
@@ -116,6 +116,19 @@ prompt:
|
||||
|
||||
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.
|
||||
|
||||
#### 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:
|
||||
|
||||
```yaml
|
||||
allow_outputs:
|
||||
- type: discord.reply
|
||||
max: 1
|
||||
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.
|
||||
|
||||
## Prompt partials
|
||||
|
||||
`include` paths are relative to `.paseo/partials/` and are resolved at the exact GitHub configuration commit. Hub stores the resolved content and SHA-256 hash in the immutable revision. Missing files, unsafe paths, symlinks, submodules, directories, and nested includes are rejected. Manual configurations cannot use repository partials.
|
||||
|
||||
@@ -44,7 +44,7 @@ Dispatch fails and the event is recorded as failed. Nothing is queued, so trigge
|
||||
|
||||
## Can an agent reply back to Slack or Discord?
|
||||
|
||||
Yes, with `allow_outputs`. It gets one plain-text thread reply per execution. On GitHub, agents reply through the scoped `GH_TOKEN` they already have, so `gh issue comment` works.
|
||||
Yes, with `allow_outputs`. See the [`hub.yml` output capability reference](/docs/hub/configuration/hub-yml#output-capabilities) for reply limits and required outputs. On GitHub, agents reply through the scoped `GH_TOKEN` they already have, so `gh issue comment` works.
|
||||
|
||||
## Can I use it without GitHub?
|
||||
|
||||
|
||||
@@ -88,4 +88,4 @@ Both run. Triggers are not ordered and do not shadow each other, in one configur
|
||||
|
||||
## Replying
|
||||
|
||||
Put `allow_outputs` on the step that should reply. The available provider reply types are `slack.reply`, `discord.reply`, and `github.reply`; set `max` when a step needs more than one update. GitHub-triggered agents also receive a scoped GitHub credential for `gh`.
|
||||
Put `allow_outputs` on the step that should reply. The Hub provider reply capabilities are `slack.reply` and `discord.reply`; set `max` when a step needs more than one update, or `required: true` when it must emit at least one reply before it can finish. A required type must be registered and available for the execution context. GitHub-triggered agents receive a scoped GitHub credential for `gh` and can comment through that credential instead of a Hub output tool. See the [`hub.yml` output capability reference](/docs/hub/configuration/hub-yml#output-capabilities) for the contract.
|
||||
|
||||
Reference in New Issue
Block a user