Files
pipelines/internal/author/skill/references/format.md
T
alan f57457aec9 Make agent-stage retries safe and retain timeout failure evidence
Fix four stage failure-handling and observability defects (A2, A3, A6, A9).

- A2: add safeToReplay(def) as the single definition of retryable post-admission
  work - only an explicit tools block that selects neither edit nor shell. The
  agent/pi WorkStarted guards now break only when the stage is not safe to
  replay, so read-only stages genuinely retry a post-admission timeout while
  mutating and legacy-bundle stages still never replay admitted work.
- A6: re-emit a malformed final result on an explicit read-only stage up to the
  retry budget, preserving format_repairs evidence; mutating stages keep the
  immediate return and their session.
- A3: timed-out stages retain usable evidence. waitForSessionIdle records one
  bounded sanitized OperationEvidence on deadline; the agent deferred cleanup
  does a bounded best-effort latest-assistant readback and settles knowable V2
  usage; RetainSession adds a retained_session pointer to failed step
  transcripts so the session is visible beneath the BoundTranscript threshold.
- A9: a stage outcome routed to #failure now yields a non-empty run diagnostic
  ("stage <name> returned outcome <outcome>") while preferring an existing step
  diagnostic.

Adds focused stage and server tests for retry safety, malformed-result
re-emission, timeout evidence retention and run-level diagnostics; updates the
packaged skill references and docs/cli.md, docs/model-results.md.
2026-10-15 18:27:22 +01:00

141 lines
7.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Definition format
Definitions are Markdown made only of `# stage KEY` headings and fenced blocks.
An optional `# settings` section precedes all stages. No unrelated prose outside
blocks. The first stage receives `input.prompt` from the runtime user's task
and `input.pwd`, the resolved run directory recorded by the server;
later stages receive previous output unless `memory` explicitly selects fields
from run-local context. There are no stage `input` blocks. Read
`references/control.md` for selected memory and runner-enforced limits.
Each model stage requires nonempty `output`, `prompt`, `configs`, and `edges` blocks:
````markdown
# stage worker
```output
{ summary, evidence, artifacts }
```
```prompt
Perform the task supplied in input.prompt. Return evidence, not invented success.
```
```configs
type=model
provider=opencode-go
model=deepseek-v4.1-flash
retries=2
timeout=1h
```
```tools
```
```edges
success -> #success
blocked -> #failure
error -> #failure
```
````
Stage/outcome keys begin with a letter and contain letters, digits, `_`, or `-`.
Each outcome has exactly one target: another stage, `#success`, or `#failure`.
An omitted error edge defaults to failure. Execution is sequential; forks choose
one outcome, never execute parallel branches. Cycles are allowed; every stage
must be reachable from entry and have a possible path to a terminal. Use bounded
runner-owned `limits` for feedback loops, never revision counters in model
prompts/outputs. Read `references/control.md` for the exact format.
Model configs may set `harness=opencode` or `harness=pi`; omission preserves
historical OpenCode execution. Read `references/harnesses.md` for setup/limits.
Use the exact provider/model IDs validated during server setup. New drafts/templates
inherit that selection; do not assume the host's login matches the container's.
Other OpenCode provider/model IDs are accepted syntactically; actual availability,
authentication and inference require `pipelines provider-check` on the execution
computer/container. Optional `retries` defaults to 2 (three total attempts),
and accepts integers 0–100; explicit 0 disables execution retries. Optional
`timeout` defaults to `1h` per attempt and accepts positive durations such as
`30m` or `90s`. Automatic retries cover retryable transport failures and
timeouts; an explicit read-only stage may additionally retry a post-admission
deadline or transport failure, while a stage with `edit`/`shell` (or no tools
block) never replays admitted work. Optional `budget_usd=1.50` and
`budget_tokens=50000` independently cap reported usage.
They accumulate across attempts, format repair sessions, and repeated visits
to this stage in the same run. Omit either budget to leave that resource unlimited.
Both budgets must be positive; tokens include input, output, reasoning and cache
reads/writes. Accounting failures stop budget-limited stages. In-flight requests
may exceed limits before usage is reported; these are not provider-side hard caps.
In current source, budgeted OpenCode V2 text-only calls use tracked prompting with
all tools denied, rather than the usage-less `/generate` path. Completed
token-budgeted responses reporting zero tokens fail closed. This is an execution
implementation detail, not a new Markdown field: never add backend/format/API
settings to definitions. Read `references/verification.md` for the dated live
accounting result and its provider/deployment limitations when relevant.
The run has no additional wall-clock deadline; step/visit caps and cancellation
still apply. A native ntfy stage accepts `timeout` but never automatically retries
delivery and has no model budget.
Explicit empty `tools` denies all; allowed tools are `read`, `glob`,
`grep`, `webfetch`, `websearch`, `edit`, `shell`, one per line. No wildcards,
delegation, or browser tools. Tools are per-stage and automatically enabled by
starting a run. `edit` supports any file type and creating files/directories in the
run directory; no file list is required. `shell` supports commands appropriate to
the repository's language and tooling, not a language-specific allowlist. A missing
tools block uses local read/glob/grep/edit/shell tools; prefer explicit stage roles.
Planning stages must not label a task blocked simply because they defer edits to
an implementer stage. Bundled starters show the intended role split: a task stage
may read/edit/shell and conditionally use `websearch`/`webfetch`; a planner may
read plus conditional web search/fetch; a three-stage implementer has no web tools
and works from the planner's research with local read/glob/grep/edit/shell; a
reviewer may read plus conditional web; a source-only review stage has no
edit/shell; a research stage uses web search/fetch. Never force web access for
trivial, fully understood local edits, and return blocked only when required
reliable evidence cannot be obtained rather than whenever one search tool fails.
Keep examples and prompts language-neutral unless the task itself asks for a
specific language.
Optional `permissions` is a JSON object with `edit` (run-directory-relative
patterns) and `shell` (exact commands) arrays. It narrows declared tools and any
run-level file scope; it never enables a missing tool. Empty arrays deny actions.
Nulls, duplicate/unknown keys, traversal and shell wildcards/chaining/redirects or
expansion are rejected. If edits are restricted and shell is enabled, provide an
explicit shell list too. Example: `{"edit":["README.md","plugin/*.qml"],"shell":["bash -n install.sh"]}`.
Use this block for intentional file/command restrictions; prose is not a runtime
permission policy. Keep ordinary workflows language-neutral and unrestricted
within their run directory unless the user asks for a narrower scope.
Malformed final JSON has bounded, syntax-only recovery even with `retries=0`;
it never changes verdict/evidence. On an explicit read-only stage a rejected
malformed result may be re-emitted up to `retries` with its `format_repairs`
evidence retained; a stage with `edit`/`shell` or no tools block never replays
stage tools or re-emits the result. Compatible native stable
backends request schema output with schema retries disabled; a retained deny-all,
no-inference compatibility probe identifies known format incompatibility. Incompatible
native backends and V2 require strict local envelope validation. Do not promise
recovery of truncated strings, missing evidence or invalid outcomes.
Return the strict `{ "outcome": "declared-edge-key", "output": { ... } }`
envelope. Do not treat tool-call/DSML markup, plain prose or flattened output as
success, or rerun tool work to fix a response's formatting.
## Scheduling
Manual-only is the default. To schedule, put `# settings` before all stages with
a nonempty fenced `prompt` and one or more fenced `schedule` blocks. Each schedule
uses exactly one of `times=09:00,17:30` or `every=15m`, optionally
`days=mon,tue,wed,thu,fri` and `timezone=Europe/London`. Intervals are at least
one minute. Submission activates the latest version's schedules immediately.
Removing settings disables schedules on the new version. Scheduled shell/edit
are not approved. Warn explicitly before adding/changing schedules.
## Notifications
Stage hooks use the global phone connection, never store credentials. Optional
fenced `notify` block: `on=success,failure`, `artifacts=markdown`.
Read this skill's `references/notifications.md` for the minimal terminal-path
recipe and optional native publisher format. Prefer hooks for ordinary success/error
alerts; a request to notify is not a request for a new delivery stage. Do not scan
the user's repository for Pipelines docs. Bundled starters are generic and manual-only.
Notification attachment/report support and model availability need real runtime
tests; structural validation alone cannot confirm delivery.