9f88e4ff71
A model stage whose final result was malformed failed the whole run even when
the work and evidence had survived, because the only recovery was an isolated
formatter call on a fixed 30-second deadline that could time out on its own
(run 55, ui_reviewer of pipeline 9 v6).
Add an ordered, deterministic local repair pass (internal/stage/result_repair.go)
that runs before any model call: (a) append missing closing delimiters via the
existing closeJSONContainers; (b) remove one unambiguous trailing comma before a
closing } or ]; (c) insert exactly the single comma/colon the JSON parser reported
at its byte offset. Every candidate must pass losslessSyntaxRepair(original,
candidate) and decodeModelResult before it is accepted, so no field value is
invented, removed, reordered or rewritten. Ambiguous payloads (an unescaped quote
or colon inside a string value, or a stray delimiter with no single completion)
return not-ok and fall through to the bounded model re-emit rather than guessing.
stageResultText still strips surrounding prose and a single code fence first;
model_prompt.go now also strips prose around a single balanced-but-malformed
object span so the deterministic pass sees just the object.
Replace the fixed 30-second formatter deadline with repairDeadline(payloadBytes,
remaining), which grows monotonically with payload size, has a floor, and is
clamped to the attempt's remaining budget minus a safety margin, so the stage
context remains the outer bound and a large result is not guaranteed to time out.
The one-request-per-attempt, 32 KiB bound and the deny-all, retained, new-session
property of RepairFormat are unchanged for OpenCodeClient and PiClient.
Record an explicit recovery status on every terminal path: repaired, partial or
unrecoverable, plus a byte offset. A candidate that is valid JSON but still fails
envelope validation is marked partial and never returned as a completed result;
the unrecoverable path retains the bounded original payload, the precise parse
error (including its byte offset) and surfaces the status in the FINAL RESULT
VALIDATION diagnostic.
safeToReplay is intentionally unchanged. The deterministic local repair and the
fresh deny-all, no-tools, retained formatter session are independent of the
stage's tool set and never re-prompt or replay the admitted agent session, so a
shell-enabled review stage gains malformed-result recovery without any replay of
admitted work. Risk: no change to mutation safety; the only added cost is one
bounded formatter call, already budgeted. Replayability is not extended for shell
stages.
Docs and packaged skill references (docs/model-results.md,
internal/author/skill/references/{format,debugging,verification}.md) describe the
three-tier recovery, the status words and the derived deadline; the safeToReplay
decision and its risk are recorded there alongside the commit.
Tests add mocked, offline coverage for the deterministic and partial paths, a
repairDeadline monotonicity/floor/clamp table, and a shell-stage regression
proving a recoverable malformed result does not fail the run or replay tool work.
149 lines
8.3 KiB
Markdown
149 lines
8.3 KiB
Markdown
# 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 recovery even with `retries=0`; it never changes
|
||
verdict/evidence. Recovery tries a deterministic local pass first (append missing
|
||
closing delimiters, drop one trailing comma, or insert the single comma/colon the
|
||
parser expected), then at most one deny-all formatter request whose deadline is
|
||
derived from the payload size and the attempt's remaining budget rather than a
|
||
fixed short constant. Every path records `repaired`, `partial` or `unrecoverable`
|
||
in `format_repairs`; a partial or unrecoverable result is never returned as
|
||
complete, and an ambiguous payload (an unescaped quote/colon inside a string
|
||
value) is never guessed at. On an explicit read-only stage a rejected malformed
|
||
result may be re-emitted up to `retries`; a stage with `edit`/`shell` or no tools
|
||
block never replays stage tools or re-emits the result, though the deterministic
|
||
pass and the fresh deny-all, tool-free formatter session still apply. 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.
|