Merge pull request #101 from edgehero/docs/triggers-and-workflows

docs: lead with triggers, and document workflows and pi extensions

Author: edgehero

.github/workflows/image.yml

@@ -8,6 +8,9 @@
 # No secret required: GHCR auth uses the built-in GITHUB_TOKEN (packages: write). One-time after the first
 # successful run: make the ghcr.io/edgehero/pi-job package Public in the org's package settings, otherwise
 # `docker pull` needs auth.
+#
+# Tags: `latest`, the git `sha`, and the PRODUCT version from the root package.json (so a release cuts a
+# tag that never moves, and a deployment can pin `ghcr.io/edgehero/pi-job:<version>` instead of tracking latest).
 
 name: image
 
@@ -16,6 +19,7 @@ on:
     branches: [main]
     paths:
       - "image/**"
+      - "package.json" # the ROOT one: a product version bump republishes under its own tag
       - ".github/workflows/image.yml"
   # Manual re-run (available once this file is on the default branch).
   workflow_dispatch: {}
@@ -46,13 +50,18 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Resolve the product version (the tag operators can pin)
+        id: v
+        run: echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+
       - name: Tags + labels
         id: meta
         uses: docker/metadata-action@v5
         with:
           images: ${{ env.IMAGE }}
           tags: |
             type=raw,value=latest
+            type=raw,value=${{ steps.v.outputs.version }}
             type=sha
 
       - name: Build + push (amd64 + arm64)

.github/workflows/receiver-image.yml

@@ -10,6 +10,9 @@
 # No secret required: GHCR auth uses the built-in GITHUB_TOKEN (packages: write). One-time after the first
 # successful run: make the ghcr.io/edgehero/pi-dispatch-receiver package Public in the org's package
 # settings, otherwise `docker pull` needs auth.
+#
+# Tags: `latest`, the git `sha`, and the PRODUCT version from the root package.json (so a release cuts a
+# tag that never moves, and a deployment can pin `ghcr.io/edgehero/pi-dispatch-receiver:<version>` instead of tracking latest).
 
 name: receiver-image
 
@@ -21,6 +24,7 @@ on:
       - "worker/src/**"
       - "worker/package.json"
       - "package-lock.json"
+      - "package.json" # the ROOT one: a product version bump republishes under its own tag
       - ".github/workflows/receiver-image.yml"
   # Manual re-run (available once this file is on the default branch).
   workflow_dispatch: {}
@@ -51,13 +55,18 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Resolve the product version (the tag operators can pin)
+        id: v
+        run: echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+
       - name: Tags + labels
         id: meta
         uses: docker/metadata-action@v5
         with:
           images: ${{ env.IMAGE }}
           tags: |
             type=raw,value=latest
+            type=raw,value=${{ steps.v.outputs.version }}
             type=sha
 
       - name: Build + push (amd64 + arm64)

README.md

@@ -33,6 +33,23 @@ Every trigger produces the same job, through the same path: one queue, one conta
 
 The container is the boundary (pi's missing permission system, enforced by Docker). Those isolation flags are built by the worker's own `docker run` argv, so nothing an image contains can weaken them; the non-root user is a property of the **image**, which is why an image has to meet the conformance checklist in [`docs/job-image.md`](https://github.com/edgehero/pi-dispatch/blob/main/docs/job-image.md). Spend is checked before a container starts, so a runaway or a junk trigger costs a refusal, not a surprise bill. The job image is yours to shape, per deployment or per trigger, and it ships Playwright and Chromium so a flow can build a frontend, screenshot it, and iterate on the render.
 
+## Triggers: what starts a job
+
+Every trigger is one `{ on, run }` entry in a single `triggers.json`, read live by the worker (cron) and the receiver (forge webhooks), and editable from the console. **`on` is what fires it; `run` is the skill it runs.**
+
+| `on.type` | Fires on | What narrows it | What the agent gets as its task |
+|---|---|---|---|
+| `cron` | your schedule | nothing: a schedule is its own condition | the `task` written in the file |
+| `label` | a label on an **issue** (or an Azure work item), never a pull request | a label predicate: `any`, `all`, or `none` (which can suppress a fire, never cause one) | the issue title and body |
+| `comment` | a comment containing your phrase, for example `@pi` | the phrase, and one comment trigger per forge | the comment body, plus the issue title and body |
+| `pull_request` | a PR or MR event | `action`, in your forge's own words, plus the same label predicate | the PR title and body |
+
+Four forges: GitHub, GitLab, Forgejo (and Gitea), Azure DevOps. **Who may fire a trigger is your forge's decision, not this service's**: on GitHub the label *is* the approval, because only collaborators can apply one, while GitLab, Forgejo and Azure resolve the actor's permission through their APIs. Each forge's action vocabulary is validated when the file loads, so a word from the wrong forge is refused instead of silently never matching.
+
+**Flows, and workflows.** `run.flow` names a skill committed to the target repo at `.pi/skills/<flow>/SKILL.md`, read from the **default branch**, so the repo owns the prompt and merging it is the repo's consent. A skill may call other skills, which is already a workflow. For typed multi-stage ones, a pi extension such as `@juicesharp/rpiv-workflow` can be staged into the deployment: pinned to an exact version, installed on your host (never at job time, since jobs run offline), loaded in every container, and declinable per trigger.
+
+**How a workflow gets triggered, in one line:** `label / comment / PR / cron` fires **one job in one container**, that job runs `run.flow`, and the flow drives whatever stages follow. Four consequences worth knowing before you build on it. A trigger names a **flow, never a workflow**, so which stages run is decided inside the job by that skill. A job is **not an interactive session** (the container hands pi one assembled prompt and reads the exit line), so a workflow extension's slash command has nobody to type it: in a job the flow's instructions drive the workflow, or a small extension you also staged calls its API from a lifecycle hook. One trigger is **one job, one budget slot and one turn budget**, so ten stages share the same `PI_MAX_TURNS` and per-job token budget, and exhausting either ends the job as a policy refusal that is never retried. And whether the workflow's own state survives depends on the trigger kind: a cron or CLI job has your folder mounted read-write so state persists between runs, while a forge job gets a fresh clone that is discarded with the container. Full reference: [`docs/workflows.md`](https://github.com/edgehero/pi-dispatch/blob/main/docs/workflows.md).
+
 ## The console: `/dispatch`
 
 One command puts a live TUI over the whole deployment:

admin/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-admin",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Operator console (a pi extension) + skill for pi-dispatch: run the pi coding agent as a self-hosted service. A /dispatch TUI for the queue, spend caps, run history, editable GitHub, GitLab, Forgejo and Azure DevOps triggers (cron/label/comment/PR/MR/work item), and scheduled pause windows — plus AI-operable, human-confirmed controls. Runs against a live pi-dispatch deployment.",
   "keywords": [
     "pi-package",

admin/package.json

@@ -52,7 +52,7 @@ type Notify = ((message: string, type?: string) => void) | undefined;
  * version, so a release bump stays atomic: bump the worker and the test fails here until this literal
  * follows in the same change.
  */
-export const RUNTIME_VERSION = "0.1.1";
+export const RUNTIME_VERSION = "0.1.2";
 
 /**
  * The `@edgehero/pi-dispatch-receiver` version the trigger-edge step installs -- pinned for exactly the
@@ -62,7 +62,7 @@ export const RUNTIME_VERSION = "0.1.1";
  * independently (the receiver's dependency range on the runtime is `^`), and pretending otherwise would
  * install a version that does not exist the first time they diverge.
  */
-export const RECEIVER_VERSION = "0.1.0";
+export const RECEIVER_VERSION = "0.1.1";
 
 /** The two npm package names, spelled once. Literals of this module -- see npmInstallArgsFor's argument. */
 const RUNTIME_PKG = "@edgehero/pi-dispatch";

admin/src/setup-wizard.ts

@@ -803,7 +803,7 @@ test("wizard: the edge's service answer installs the PINNED receiver, then the -
   assert.equal(attached.length, 2, "the npm install and the unit install — nothing else");
   assert.equal(attached[0].argv0, "npm", "posix npm, per npmSpawnOptions");
   assert.deepEqual(attached[0].args, mod.npmInstallArgsFor(RECEIVER_PKG, mod.RECEIVER_VERSION));
-  assert.ok(attached[0].args.includes(`${RECEIVER_PKG}@0.1.0`), "the pinned name@version token, spelled out");
+  assert.ok(attached[0].args.includes(`${RECEIVER_PKG}@0.1.1`), "the pinned name@version token, spelled out");
   assert.equal(attached[0].cwd, dir, "installed into the deployment dir, by cwd");
   assert.deepEqual(
     JSON.parse(readFileSync(join(dir, "package.json"), "utf8")),
@@ -817,7 +817,7 @@ test("wizard: the edge's service answer installs the PINNED receiver, then the -
   assert.equal(attached[1].cwd, dir);
 
   const c = seen.confirm.find((x) => /receiver/i.test(x.title));
-  assert.match(c.message, new RegExp(`${RECEIVER_PKG.replace("/", "\\/")}@0\\.1\\.0`), "the confirm shows the exact pin");
+  assert.match(c.message, new RegExp(`${RECEIVER_PKG.replace("/", "\\/")}@0\\.1\\.1`), "the confirm shows the exact pin");
   assert.match(c.message, /service install --receiver/, "and the unit command it will run after");
   assert.ok(c.message.includes(dir), "and names the cwd");
   assert.ok(reachedFirstTrigger(seen), "the wizard continued to step 11");

admin/test/setup-wizard.test.mjs

@@ -118,7 +118,9 @@ be in the overlay. Never place the admin extension there (it can enqueue paid jo
 
 ## Packages (pinned, per-trigger)
 
-A **pi package** is third-party code from npm that contributes extensions, skills, prompts and themes. Every
+A **pi package** is third-party code from npm that contributes extensions, skills, prompts and themes. This
+is also the road a **workflow extension** takes into a job, and what a workflow can and cannot keep across
+jobs is its own reference: [`workflows.md`](workflows.md). Every
 job runs with `PI_OFFLINE=1`, which makes pi's resolver **refuse to shell out to npm**, so a package cannot
 be installed at job time: you stage it on **your host**, into the overlay, and a trigger opts in. Note what
 is doing the work here. The container's network is **not** cut off (egress is open, as above, and

docs/global-pi-overlay.md

@@ -36,6 +36,12 @@ a second thing to forget to bump. Re-declare only a label whose truth your layer
 single re-declared `dev.pi-dispatch.forges` with `azure` appended (see
 [azure-devops.md](azure-devops.md), which also names the `--build-arg BASE=…` you need).
 
+**Pin the base if you would rather not track `latest`.** Every published build also carries the **product
+version** as a tag (`ghcr.io/edgehero/pi-job:0.8.0`) and the git `sha`, and neither ever moves, while
+`latest` follows `main`. The receiver image is tagged the same way. A pinned base is the honest choice for a
+derived image whose layer assumes something about the base; the cost is that a pin does not pick up a
+security rebuild, so bump it deliberately.
+
 **Copy `image/Dockerfile` and add to it.** You inherit every property in the checklist below for free, and
 the only thing you own is your own `RUN apt-get install …` layer. Prefer this over the layer above only when
 you need to change something *inside* the base build (a different base distro, a different pi pin).