Merge main; align lint and skill practices with essential memory/history and the four graded examples
This commit is contained in:
+78
-28
@@ -71,8 +71,9 @@ token-reporting stage reported one, and the summed cost, plus counts of stages
|
||||
that did or did not report a cost. A stage whose provider reported no cost is
|
||||
counted as cost-unknown and never contributes a fabricated or zero cost, and no
|
||||
cost/token count is inferred from output length or transcript text. The totals are
|
||||
the sum of the per-run totals `inspect` shows. `pipelines stats --json` exposes
|
||||
these aggregates.
|
||||
the sum of the per-run totals `inspect` shows. Only usage rows whose recorded
|
||||
step still exists are counted, so rows orphaned by an old history wipe are ignored
|
||||
(not deleted). `pipelines stats --json` exposes these aggregates.
|
||||
|
||||
Use `:status` on any TUI page to open server and ntfy information. Scroll with
|
||||
arrows or `j/k`, PgUp/PgDn; `r` refreshes and Esc closes without changing the page.
|
||||
@@ -152,7 +153,7 @@ pipelines edit # fuzzy pipeline selection
|
||||
pipelines edit "bug fix" # ask the harness what to change
|
||||
pipelines edit "bug fix" "Add a review step"
|
||||
pipelines new "release notes" "Summarize changes and notify my phone"
|
||||
pipelines new "Add a feature" --template task
|
||||
pipelines new "Add a feature" --template feedback-loop
|
||||
```
|
||||
|
||||
`new` opens the configured harness (Pi or OpenCode; host by default, or
|
||||
@@ -213,27 +214,21 @@ is not ownership (the kernel lock is). This is a local-filesystem lock, not a
|
||||
distributed lease; hard-link database aliases and filesystems without reliable
|
||||
advisory locking are unsupported.
|
||||
|
||||
Use `:templates` for four simple, manual-only starters: task, review, research,
|
||||
and plan/implement/review. **Submit template** (`s` or Enter) asks for a
|
||||
Use `:templates` for the four manual-only examples, read in order: one stage,
|
||||
two stages, a feedback loop and a human decision (`examples/README.md`). A
|
||||
brand-new database already holds them as ordinary pipelines; the server seeds
|
||||
them once and never again, so removing them or upgrading never brings them back.
|
||||
**Submit template** (`s` or Enter) asks for a
|
||||
name without opening an editor. Enter saves a retained draft, then a separate
|
||||
confirmation publishes it as a new pipeline. Esc before naming creates nothing;
|
||||
Esc at publication keeps the draft. **Customize** (`e`) opens the editor picker
|
||||
instead. Both paths inherit the configured default model and preserve existing
|
||||
pipelines/history. The research starter requires configured web search support.
|
||||
Starter stages use goal-appropriate tools: the task worker and the three-stage
|
||||
implementer edit and run checks, the task, planner and review stages may
|
||||
search/fetch official sources only when external knowledge is genuinely needed,
|
||||
the three-stage implementer has no web tools and follows the planner's research,
|
||||
the standalone review stage never edits or runs commands and says so explicitly,
|
||||
and the three-stage reviewer independently inspects the real changes and receives
|
||||
the planner-owned acceptance checks rather than the implementer's summary,
|
||||
approving only when the applicable acceptance checks were independently observed
|
||||
passing and no unresolved substantive issue remains. The task and three-stage
|
||||
templates end in a committer stage that stages the runner's captured changed paths
|
||||
and commits locally without ever pushing; a genuine operator gate is a `type=human`
|
||||
decision stage, never a model stage pretending to approve. Editing a bundled
|
||||
template source changes no installed or published definition; a starter becomes an
|
||||
immutable version only after explicit authoring and publication.
|
||||
pipelines/history. Only the stages that make the requested change (`implement`,
|
||||
`act`) may edit; the others read, and the loop's reviewer also runs read-only
|
||||
checks. No example commits, pushes or deploys. A genuine operator gate is a
|
||||
`type=human` decision stage, never a model stage pretending to approve. Editing a
|
||||
bundled template source changes no installed or published definition; a template
|
||||
becomes an immutable version only after explicit authoring and publication.
|
||||
|
||||
Home's `n` / `:new` and **Customize** (`e`) on a template first ask how to author the new
|
||||
pipeline: **nvim** opens a retained Markdown draft file, or a configured harness
|
||||
@@ -284,6 +279,19 @@ pipelines validate /path/to/pipeline-123.md --json
|
||||
pipelines submit /path/to/pipeline-123.md --json
|
||||
```
|
||||
|
||||
`validate` and `submit` apply the authoring lint to new drafts (stored versions
|
||||
keep loading and running unchanged). Errors reject the draft and are listed
|
||||
together, one `stage KEY: RULE: message` per line: a stage that can modify the
|
||||
workspace without a `checks` block (`none: <reason>` or, on a `delivery=true`
|
||||
stage, the commands), a prompt naming an undeclared outcome ("report skipped"),
|
||||
a "the server lands it" claim with no `delivery=true` stage, a loop edge without
|
||||
`limits`, and a check guard that passes without running (`|| true`,
|
||||
`[ ! -x tool ] || ...`). Warnings print as `warning: ...` on stderr (the
|
||||
`warnings` array with `--json`) and do not block: runner boilerplate in a prompt,
|
||||
a prompt over 2000 bytes, an instruction to read the full history every visit,
|
||||
and back-quoted non-outcome words after return/report. The skill's
|
||||
`references/practices.md` explains each rule.
|
||||
|
||||
`--json` never opens an editor or picker; provide a name explicitly. It returns
|
||||
draft metadata including `path`, `name`, `server`, `create_only`, and `base_version`.
|
||||
`--no-open` prints the path and review commands. `$PIPELINES_DRAFT_DIR` overrides
|
||||
@@ -349,8 +357,23 @@ Every run summary (`list_runs` rows, `get_run`, subscribe snapshots and terminal
|
||||
with turn documents and session exports, server-created Pi session directories,
|
||||
plus an estimate of its database rows). It is cached in `pipeline_runs.size_bytes`,
|
||||
invalidated by triggers when the run changes, measured on completion, and
|
||||
backfilled in the background; 0 means not measured yet. `delete_runs` removes
|
||||
finished runs to free space:
|
||||
backfilled in the background; 0 means not measured yet.
|
||||
|
||||
`list_runs` rows (and `get_run`) also carry `usage`, the run's totalled reported
|
||||
model usage, in the same shape as the run detail's total: `tokens_total`,
|
||||
`stages` and `tokens_known_stages` (the total is partial when fewer stages
|
||||
reported tokens than recorded usage), the `tokens_in`/`tokens_out` split with
|
||||
`split_known`, the `tokens_reasoning`/`cache_read`/`cache_write` components with
|
||||
`cache_known` (true only when every token-reporting stage recorded them;
|
||||
`tokens_total` includes cache reads, which dominate for a caching harness), and
|
||||
`cost_usd` with `cost_known_stages`/`cost_unknown_stages`. The list computes it
|
||||
with one grouped SQL aggregate per batch of 100 runs over the stored per-stage
|
||||
usage rows joined to their recorded steps, never a step load or transcript parse.
|
||||
It is omitted for a run with no recorded model usage; an older server omits it on
|
||||
every row, and clients then show nothing. Subscribe snapshots and `run_event`
|
||||
frames do not carry it, so a running run's total refreshes with the next list.
|
||||
|
||||
`delete_runs` removes finished runs to free space:
|
||||
|
||||
```json
|
||||
{"type":"delete_runs","id":"1","run_ids":[12,13,99]}
|
||||
@@ -461,6 +484,20 @@ sessions pipeline runs create. The protocol types are:
|
||||
for the run that owns them. The list is fail-closed: with no registry and no
|
||||
store it returns an empty list, never the endpoint's whole session list. A
|
||||
session is never marked `busy`: any number of clients may watch and write one.
|
||||
Each row carries `activity` (`turn_running`, `background_tasks`, `seq`): the
|
||||
server's live view of the session. An older server omits it.
|
||||
- `chat_activity` is pushed to every open connection, not only the chat's
|
||||
watchers, when a session's turn starts or ends or its count of running
|
||||
background tasks changes (shells, background commands, Claude Code background
|
||||
Bash and subagents, Codex command executions). The body is `chat_activity`
|
||||
(`session_id`, `turn_running`, `background_tasks`, `seq`). It is sent on those
|
||||
transitions only, never per output chunk. `seq` increases with every change
|
||||
and keeps increasing across a restart, so a client keeps the snapshot (list
|
||||
row or push) with the larger `seq`. Background tasks are counted only while
|
||||
the server observes the session: after a chat's last viewer leaves, the
|
||||
server keeps observing it while its tasks run (bounded like an unattended
|
||||
turn: at most 16 such chats and 6 hours). Once released it reports none
|
||||
rather than a stale count.
|
||||
- `chat_subscribe` attaches a connection to one session's shared live stream (body
|
||||
`session_id`) and replays the session's still-pending approval requests, so every
|
||||
client that watches a session sees every frame any client's turn produces — the
|
||||
@@ -627,8 +664,12 @@ per-step `provider`/`model`, and the run's graph shows the effective pair). Each
|
||||
model step also records the usage the harness reported, carried from the same
|
||||
accounting the stage already used for its budget: `usage.tokens_total`, the
|
||||
`tokens_in`/`tokens_out` split when the harness reported it (`split_known`),
|
||||
`cost_usd` when reported, and the explicit `tokens_known`/`cost_known`/
|
||||
`split_known` markers. The run detail totals those stages as `usage`, so a
|
||||
`cost_usd` when reported, the `tokens_reasoning`/`cache_read`/`cache_write`
|
||||
components when the harness reported the component split (`cache_known`; rows
|
||||
recorded before these were kept lack it, so their cache share is unknown), and
|
||||
the explicit `tokens_known`/`cost_known`/`split_known` markers. Some subscription
|
||||
providers report `cost_known` with no positive `cost_usd`; clients show that cost
|
||||
as not reported, never as $0. The run detail totals those stages as `usage`, so a
|
||||
mixed-model run shows each stage's model, tokens and cost and the run total. A
|
||||
stage whose provider reported no cost shows its tokens with `cost_known: false`
|
||||
(never a fabricated or zero cost), and a harness that reports only a total (Pi)
|
||||
@@ -637,6 +678,13 @@ total as input tokens. The
|
||||
CLI is the deliverable; a TUI picker for choosing overrides is a documented
|
||||
follow-up, not half-built.
|
||||
|
||||
The run detail (`inspect <id> --json`, `get_run`) also carries an additive
|
||||
top-level `warnings` string list, derived at read time from the steps; `inspect`
|
||||
repeats each entry on stderr as `warning: ...`. Today it names every visit whose
|
||||
retained file-change capture was `partial` or `unavailable`, because such a
|
||||
capture is not a complete workspace diff and disables the server skip fallback
|
||||
(see [stage-file-diffs.md](stage-file-diffs.md)). Older peers ignore the field.
|
||||
|
||||
|
||||
On either the runs list or run inspector, press `P` (or use `:pipeline`) to open
|
||||
the selected run's exact pipeline version. Navigation does not cancel the run.
|
||||
@@ -754,6 +802,7 @@ files as that step's artifacts:
|
||||
```
|
||||
<artifacts>/<run>/stages/01-implementer/input.md
|
||||
<artifacts>/<run>/stages/01-implementer/memory.md
|
||||
<artifacts>/<run>/stages/01-implementer/history.md
|
||||
<artifacts>/<run>/stages/01-implementer/output.md
|
||||
<artifacts>/<run>/stages/01-implementer/private/
|
||||
<artifacts>/<run>/public/
|
||||
@@ -761,10 +810,11 @@ files as that step's artifacts:
|
||||
|
||||
`input.md` is the run prompt on the first visit; later visits carry the run
|
||||
prompt under `# Run task` followed by the previous visit's output body (without
|
||||
its outcome section) under `# Previous turn output`. `memory.md` is the accumulated markdown of completed turns plus the
|
||||
files each turn added to the shared `public/` directory. A text-only stage (an
|
||||
explicit empty `tools` block) receives both files' contents in its prompt
|
||||
instead, because it has no file-reading tool. The model returns the complete
|
||||
its outcome section) under `# Previous turn output`. `memory.md` is the capped (4 KB) essential memory inlined in every prompt: task,
|
||||
previous stage's `# handoff`, outcome ledger and changed files. `history.md` is
|
||||
the accumulated markdown of completed turns plus the files each turn added to
|
||||
the shared `public/` directory, read on demand. A stage without `read` also
|
||||
receives `input.md` in its prompt (capped), because it has no file-reading tool. The model returns the complete
|
||||
`output.md` markdown; only its `# outcome` section is interpreted by the server.
|
||||
Everything else is free-form and preserved under the step's `markdown` output.
|
||||
`private/` belongs to its own visit, while `public/` is shared by every stage in
|
||||
|
||||
Reference in New Issue
Block a user