stageflow 0.35.0 → 0.39.0

package/examples/memory/desk.pipeline.yaml

@@ -0,0 +1,192 @@
+id: desk
+memories:
+  - new-notebook
+stages:
+  - id: file-batch
+    entry: true
+    route:
+      - to: decide
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "focus", "decision", "query", and "cards". "cards" is a list of objects with "key" and "note".
+      Do these steps in order, then stop:
+      1. Call read_memory with memory "new-notebook". Keep that text. Do not call replace_memory.
+      2. For each card, in order, call add_memory_card with memory "new-notebook", that key, and content set to that note. A key may contain "/", spaces, or "@". Pass it through unchanged.
+      3. For each card, call read_memory_card with memory "new-notebook" and that key. The body must equal the note you just wrote.
+      4. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"cover":"<the exact read_memory text>","filed":"<a JSON array of {key, note} for every card, in the same order>","focus":"<focus>","decision":"<decision>","query":"<query>"}.
+      Do not call update_memory_card. Do not call any memory id other than new-notebook. Do not write files. If any add_memory_card fails, stop and emit status failure. Do not keep filing after a failure.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - focus
+            - decision
+            - query
+            - cards
+          properties:
+            focus:
+              type: string
+            decision:
+              type: string
+            query:
+              type: string
+            cards:
+              type: array
+              minItems: 2
+              items:
+                type: object
+                required:
+                  - key
+                  - note
+                properties:
+                  key:
+                    type: string
+                  note:
+                    type: string
+                additionalProperties: false
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - cover
+            - filed
+            - focus
+            - decision
+            - query
+          properties:
+            cover:
+              type: string
+            filed:
+              type: string
+            focus:
+              type: string
+            decision:
+              type: string
+            query:
+              type: string
+          additionalProperties: false
+  - id: decide
+    route:
+      - to: audit
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The input has "cover", "filed", "focus", "decision", and "query".
+      Do these steps in order, then stop:
+      1. Call search_memory_cards with memory "new-notebook" and the query. Do not treat a short hit list as permission to skip a card. There may be more matches than the tool returns.
+      2. Call read_memory_card with memory "new-notebook" and the focus key.
+      3. Call update_memory_card with memory "new-notebook", the focus key, and content set to the decision. This replaces the whole card. Do not update any other key.
+      4. Call read_memory_card again with memory "new-notebook" and the focus key.
+      5. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"cover":"<the cover you were given, unchanged>","filed":"<the filed text you were given, unchanged>","focus":"<focus>","decision":"<decision>","query":"<query>","before":"<the first read of the focus card>","after":"<the second read of the focus card>","hits":"<the search result as JSON text>"}.
+      Do not call add_memory_card or replace_memory. Do not call any memory id other than new-notebook. Do not write files. If the focus card is missing, emit status failure.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - cover
+            - filed
+            - focus
+            - decision
+            - query
+          properties:
+            cover:
+              type: string
+            filed:
+              type: string
+            focus:
+              type: string
+            decision:
+              type: string
+            query:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - cover
+            - filed
+            - focus
+            - decision
+            - query
+            - before
+            - after
+            - hits
+          properties:
+            cover:
+              type: string
+            filed:
+              type: string
+            focus:
+              type: string
+            decision:
+              type: string
+            query:
+              type: string
+            before:
+              type: string
+            after:
+              type: string
+            hits:
+              type: string
+          additionalProperties: false
+  - id: audit
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The input has "cover", "filed", "focus", "decision", "before", and "after".
+      "filed" is a JSON array of objects with "key" and "note".
+      Do these steps in order, then stop:
+      1. Call read_memory with memory "new-notebook".
+      2. Call read_memory_card with memory "new-notebook" and the focus key.
+      3. For every other key in "filed", call read_memory_card with memory "new-notebook" and that key.
+      4. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"focus":"<focus>","after":"<the focus card body you just read>","untouched":"<one line per other key, as key then a tab then the body>","page":"<the exact cover you just read>","cover_same":"yes or no"}.
+      Set cover_same to yes only when the cover you just read is exactly the "cover" you were given. Set it to no otherwise.
+      The focus body should equal "decision". Each other body should equal the note in "filed" for that key. Do not call add_memory_card, update_memory_card, or replace_memory. Do not write files.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - cover
+            - filed
+            - focus
+            - decision
+            - before
+            - after
+          properties:
+            cover:
+              type: string
+            filed:
+              type: string
+            focus:
+              type: string
+            decision:
+              type: string
+            before:
+              type: string
+            after:
+              type: string
+          additionalProperties: true
+      output:
+        schema:
+          type: object
+          required:
+            - focus
+            - after
+            - untouched
+            - page
+            - cover_same
+          properties:
+            focus:
+              type: string
+            after:
+              type: string
+            untouched:
+              type: string
+            page:
+              type: string
+            cover_same:
+              type: string
+          additionalProperties: false

package/examples/memory/file-card.pipeline.yaml

@@ -0,0 +1,39 @@
+id: file-card
+stages:
+  - id: file
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "key" and "note".
+      Do these steps in order, then stop:
+      1. Call add_memory_card with memory "notebook", that key, and content set to the note.
+      2. Call read_memory_card with memory "notebook" and that key.
+      3. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"key":"<the key>","note":"<the exact text read_memory_card returned>"}.
+      Do not call replace_memory. Do not call update_memory_card. Do not call any memory id other than notebook. Do not write files. If add_memory_card returns MEMORY_CARD_EXISTS, stop and emit status failure with the same payload shape and the error code in the summary.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false
+memories:
+  - notebook

package/examples/memory/file-ledger.task.yaml

@@ -0,0 +1,22 @@
+id: file-ledger
+goal: File the refund ledger as a card, keeping the table
+context: Memory new-notebook already exists. This key does not.
+constraints: The card body is the note exactly. Do not change the cover.
+input:
+  key: orders/4412/ledger
+  note: |
+    # Refund ledger — order 4412
+
+    Customer asked for store credit. Finance paid the original card instead.
+
+    | When | Who | Action | Amount |
+    | --- | --- | --- | --- |
+    | 2026-10-18 09:12 | grace@example.com | Request opened | 86.40 USD |
+    | 2026-10-18 11:04 | TICKET-2040 | Store credit declined | — |
+    | 2026-10-19 16:22 | payments | Paid to original card | 86.40 USD |
+
+    Still open:
+
+    - [ ] Customer confirmed the payout
+    - [x] Reviewer recorded the decline
+    - [ ] Receipt attached to the ticket

package/examples/memory/file-release.task.yaml

@@ -0,0 +1,24 @@
+id: file-release
+goal: File the release card with a table and the rollback command
+context: Memory new-notebook already exists. This key does not. It is not the older releases/2.4.1 card.
+constraints: The card body is the note exactly. Do not change the cover.
+input:
+  key: releases/2.5.0
+  note: |
+    # Release 2.5.0
+
+    Held. Do not deploy until the checkout incident on `TICKET-3180` is closed.
+
+    | Check | State | Owner |
+    | --- | --- | --- |
+    | Payments migration | reverted on 2.4.1 | payments |
+    | EU checkout | recovered 16:40 UTC | ada@example.com |
+    | This release | held | release desk |
+
+    Rollback command that was used for 2.4.1:
+
+    ```
+    sf runs rerun --run <previous> --from payments-migrate
+    ```
+
+    Decision: ship 2.5.0 only after a clean EU checkout hour, with the migration left out.

package/examples/memory/file-rich.pipeline.yaml

@@ -0,0 +1,40 @@
+id: file-rich
+memories:
+  - new-notebook
+stages:
+  - id: file
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "key" and "note".
+      The note is the full card body. It may contain headings, lists, tables, and fenced blocks. Copy it unchanged.
+      Do these steps in order, then stop:
+      1. Call add_memory_card with memory "new-notebook", that key, and content set to the note exactly. Do not summarize, rewrap, or drop a line.
+      2. Call read_memory_card with memory "new-notebook" and that key.
+      3. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"key":"<the key>","note":"<the exact text read_memory_card returned>"}.
+      Do not call replace_memory. Do not call update_memory_card. Do not call any memory id other than new-notebook. Do not write files. If add_memory_card returns MEMORY_CARD_EXISTS, stop and emit status failure.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false

package/examples/memory/file-ticket.task.yaml

@@ -0,0 +1,7 @@
+id: file-ticket-1842
+goal: File one ticket card in the shared notebook
+context: First card for this ticket. The cover page is separate.
+constraints: One card. Do not change the cover.
+input:
+  key: TICKET-1842
+  note: Refund approved for order 4412. Customer asked for store credit.

package/examples/memory/file-timeline.task.yaml

@@ -0,0 +1,28 @@
+id: file-timeline
+goal: File the checkout outage as a structured card
+context: Memory new-notebook already exists. This key does not.
+constraints: The card body is the note exactly. Do not change the cover.
+input:
+  key: TICKET-3180
+  note: |
+    # Checkout 502s — EU
+
+    ## What broke
+
+    EU checkout returned 502 from 14:10 UTC. The payments migration in `releases/2.4.1` was the trigger. US traffic stayed up.
+
+    ## Timeline
+
+    1. **14:10** — Error rate crossed 8% on `POST /checkout`.
+    2. **14:22** — On-call paged `ada@example.com`.
+    3. **15:05** — Rollback of `releases/2.4.1` started.
+    4. **16:40** — 502s stopped.
+
+    ## Not the cause
+
+    > The storefront cache was flushed at 13:40. That was a separate change and the 502s started later, only in EU.
+
+    ## Next
+
+    - Write the rollback note on `releases/2.4.1`
+    - Keep this ticket as the incident record

package/examples/memory/find-card.pipeline.yaml

@@ -0,0 +1,46 @@
+id: find-card
+stages:
+  - id: find
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "key" and "query".
+      Do these steps in order, then stop:
+      1. Call read_memory_card with memory "notebook" and that key.
+      2. Call search_memory_cards with memory "notebook" and that query.
+      3. Call read_memory with memory "notebook".
+      4. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"key":"<the key>","note":"<the exact card body>","hits":"<the search result as JSON text>","page":"<the exact cover>"}.
+      Do not call add_memory_card, update_memory_card, or replace_memory. Do not call any memory id other than notebook. Do not write files.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - key
+            - query
+          properties:
+            key:
+              type: string
+            query:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+            - hits
+            - page
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+            hits:
+              type: string
+            page:
+              type: string
+          additionalProperties: false
+memories:
+  - notebook

package/examples/memory/find-ticket.task.yaml

@@ -0,0 +1,7 @@
+id: find-ticket-1842
+goal: Read the ticket card and search the notebook
+context: A later run. The card should already be filed under TICKET-1842.
+constraints: Do not change the card or the cover.
+input:
+  key: TICKET-1842
+  query: refund

package/examples/memory/missing.pipeline.yaml

@@ -0,0 +1,16 @@
+id: missing-memory
+memories:
+  - does-not-exist
+stages:
+  - id: blocked
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      This pipeline must not start. The memory it names does not exist.
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object

package/examples/memory/recall.pipeline.yaml

@@ -0,0 +1,24 @@
+id: recall
+memories:
+  - notebook
+stages:
+  - id: read-page
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      Call read_memory with memory "notebook". Do not call replace_memory.
+      Then call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"page":"<the exact text read_memory returned>"}.
+      Do not change the page. Do not write files.
+    io:
+      input:
+        schema:
+          type: object
+      output:
+        schema:
+          type: object
+          required:
+            - page
+          properties:
+            page:
+              type: string
+          additionalProperties: false

package/examples/memory/recall.task.yaml

@@ -0,0 +1,5 @@
+id: recall-notebook
+goal: Read the shared notebook and report the page exactly
+context: A later pipeline, attached to the same memory
+constraints: Do not change the page
+input: {}

package/examples/memory/remember-ada.task.yaml

@@ -0,0 +1,6 @@
+id: remember-ada
+goal: Add Ada to the shared notebook
+context: First note in an empty notebook
+constraints: One line only. Do not drop earlier lines.
+input:
+  note: Ada was sourced.

package/examples/memory/remember-grace.task.yaml

@@ -0,0 +1,6 @@
+id: remember-grace
+goal: Add Grace to the shared notebook
+context: The notebook already has earlier lines. Keep them.
+constraints: One new line only. Do not drop earlier lines.
+input:
+  note: Grace was shortlisted.

package/examples/memory/remember.pipeline.yaml

@@ -0,0 +1,58 @@
+id: remember
+stages:
+  - id: record
+    entry: true
+    route:
+      - to: confirm
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has one field, "note".
+      Do these steps in order, then stop:
+      1. Call read_memory with memory "notebook".
+      2. Call replace_memory with memory "notebook". Set content to the previous page, unchanged, then a newline if the page was not empty, then one new line "- " followed by the note. Keep every earlier line.
+      3. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"note":"<the note>","page":"<the full new page>"}.
+      Do not call any memory id other than notebook. Do not write files.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - note
+          properties:
+            note:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - note
+            - page
+          properties:
+            note:
+              type: string
+            page:
+              type: string
+          additionalProperties: false
+  - id: confirm
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      Call read_memory with memory "notebook". Do not call replace_memory.
+      Then call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"page":"<the exact text read_memory returned>"}.
+      Do not change the page. Do not write files.
+    io:
+      input:
+        schema:
+          type: object
+          additionalProperties: true
+      output:
+        schema:
+          type: object
+          required:
+            - page
+          properties:
+            page:
+              type: string
+          additionalProperties: false
+memories:
+  - notebook

package/examples/memory/stageflow.yaml

@@ -0,0 +1,12 @@
+version: 1
+model: openrouter/nvidia/nemotron-3.5-lightning:free
+catalog:
+  pipelines:
+    - .
+  tasks:
+    - .
+  patterns:
+    pipeline: "*.pipeline.yaml"
+    task: "*.task.yaml"
+  exclude:
+    - missing.pipeline.yaml

package/examples/memory/update-card.pipeline.yaml

@@ -0,0 +1,43 @@
+id: update-card
+memories:
+  - notebook
+stages:
+  - id: revise
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "key" and "note".
+      Do these steps in order, then stop:
+      1. Call read_memory_card with memory "notebook" and that key.
+      2. Call update_memory_card with memory "notebook", that key, and content set to the note.
+      3. Call read_memory_card again with memory "notebook" and that key.
+      4. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"key":"<the key>","before":"<the first read>","note":"<the second read>"}.
+      Do not call add_memory_card. Do not call replace_memory. Do not call any memory id other than notebook. Do not write files. If the first read returns MEMORY_CARD_NOT_FOUND, stop and emit status failure.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - key
+            - before
+            - note
+          properties:
+            key:
+              type: string
+            before:
+              type: string
+            note:
+              type: string
+          additionalProperties: false

package/examples/memory/update-ledger.task.yaml

@@ -0,0 +1,23 @@
+id: update-ledger
+goal: Replace the refund ledger after the customer confirmed the payout
+context: orders/4412/ledger already exists on new-notebook. This replaces that card and leaves the previous copy for the operator.
+constraints: The card body is the note exactly. Do not change the cover. Do not add a second card.
+input:
+  key: orders/4412/ledger
+  note: |
+    # Refund ledger — order 4412
+
+    Closed. The customer confirmed the payout.
+
+    | When | Who | Action | Amount |
+    | --- | --- | --- | --- |
+    | 2026-10-18 09:12 | grace@example.com | Request opened | 86.40 USD |
+    | 2026-10-18 11:04 | TICKET-2040 | Store credit declined | — |
+    | 2026-10-19 16:22 | payments | Paid to original card | 86.40 USD |
+    | 2026-10-20 09:03 | customer | Confirmed payout | 86.40 USD |
+
+    Still open:
+
+    - [x] Customer confirmed the payout
+    - [x] Reviewer recorded the decline
+    - [x] Receipt attached to the ticket

package/examples/memory/update-rich.pipeline.yaml

@@ -0,0 +1,44 @@
+id: update-rich
+memories:
+  - new-notebook
+stages:
+  - id: revise
+    entry: true
+    model: openrouter/nvidia/nemotron-3.5-lightning:free
+    system_prompt: |
+      The task input has "key" and "note".
+      The note is the full new card body. Copy it unchanged, including tables and lists.
+      Do these steps in order, then stop:
+      1. Call read_memory_card with memory "new-notebook" and that key.
+      2. Call update_memory_card with memory "new-notebook", that key, and content set to the note exactly.
+      3. Call read_memory_card again with memory "new-notebook" and that key.
+      4. Call emit_stage_envelope once with status success, a one-line summary, artifacts [], and payload {"key":"<the key>","before":"<the first read>","note":"<the second read>"}.
+      Do not call add_memory_card or replace_memory. Do not call any memory id other than new-notebook. Do not write files. If the card is missing, emit status failure.
+    io:
+      input:
+        schema:
+          type: object
+          required:
+            - key
+            - note
+          properties:
+            key:
+              type: string
+            note:
+              type: string
+          additionalProperties: false
+      output:
+        schema:
+          type: object
+          required:
+            - key
+            - before
+            - note
+          properties:
+            key:
+              type: string
+            before:
+              type: string
+            note:
+              type: string
+          additionalProperties: false

package/examples/memory/update-ticket.task.yaml

@@ -0,0 +1,7 @@
+id: update-ticket-1842
+goal: Replace the ticket card with a later decision
+context: The card TICKET-1842 already exists. This run changes that card only.
+constraints: Do not add a second card. Do not change the cover.
+input:
+  key: TICKET-1842
+  note: Refund paid out for order 4412. Store credit was declined.