{ "$schema": "https://pi-tui.ratstack.sh/schema/pattern.schema.json", "aka": [ "Conditional actions" ], "animated": false, "apis": [ { "name": "ctx.ui.custom", "url": "https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/tui.md#use-custom-screens-and-overlays" }, { "name": "SelectList", "url": "https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/tui.md#compose-built-in-components" }, { "name": "Text", "url": null } ], "applicability": [ "Use this when only some actions are valid for the selected job." ], "category": "dialogs", "categoryLabel": "Overlays and dialogs", "consequences": [ "The chooser exposes only applicable actions.", "Choices must be rebuilt when control or execution state changes." ], "family": "behavioral", "familyLabel": "Behavioral", "id": "action-sieve", "implementation": [ "Omit unavailable actions instead of allowing an invalid transition.", "Keep dialog choice separate from job execution state." ], "intent": "Derive dialog choices from current control and completion state.", "jsonUrl": "https://pi-tui.ratstack.sh/patterns/action-sieve.json", "kind": "component", "knownUses": [ { "example": "shell-takeover-dialog", "moreRefs": 0, "refs": [ { "file": "overlay-component.ts", "lines": "600-730", "sha": "77df9a81", "url": "https://github.com/nicobailon/pi-interactive-shell/blob/77df9a8142a2f731635a4c5a01d68feecb5cced4/overlay-component.ts#L600-L730" } ], "repo": "pi-interactive-shell", "repoUrl": "https://github.com/nicobailon/pi-interactive-shell", "title": "Represent completion choices as an explicit dialog state" } ], "linkedFrom": [ { "how": "filters choices before confirmation", "id": "warning-gate", "jsonUrl": "https://pi-tui.ratstack.sh/patterns/warning-gate.json", "mdUrl": "https://pi-tui.ratstack.sh/patterns/warning-gate.md", "name": "Warning Gate", "url": "https://pi-tui.ratstack.sh/patterns/warning-gate/" }, { "how": "derives currently available choices", "id": "settings-bench", "jsonUrl": "https://pi-tui.ratstack.sh/patterns/settings-bench.json", "mdUrl": "https://pi-tui.ratstack.sh/patterns/settings-bench.md", "name": "Settings Bench", "url": "https://pi-tui.ratstack.sh/patterns/settings-bench/" }, { "how": "offers only valid handoff actions", "id": "control-baton", "jsonUrl": "https://pi-tui.ratstack.sh/patterns/control-baton.json", "mdUrl": "https://pi-tui.ratstack.sh/patterns/control-baton.md", "name": "Control Baton", "url": "https://pi-tui.ratstack.sh/patterns/control-baton/" } ], "links": { "agentGuide": "https://pi-tui.ratstack.sh/llms.txt", "index": "https://pi-tui.ratstack.sh/patterns.md", "skill": "https://pi-tui.ratstack.sh/skills/build-pi-tui-component.md" }, "mdUrl": "https://pi-tui.ratstack.sh/patterns/action-sieve.md", "motivation": "Interactive Shell's dialog omits return-to-agent unless the control state permits it.", "name": "Action Sieve", "participants": [ { "name": "ctx.ui.custom", "role": "Mounts one interaction and resolves through done.", "url": "https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/tui.md#use-custom-screens-and-overlays" }, { "name": "SelectList", "role": "Owns a bounded selection list and selection callbacks.", "url": "https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/tui.md#compose-built-in-components" }, { "name": "Control snapshot", "role": "Determines which actions are currently applicable.", "url": null } ], "pi": "1.0.3", "related": [ { "how": "changes control ownership", "id": "control-baton", "jsonUrl": "https://pi-tui.ratstack.sh/patterns/control-baton.json", "mdUrl": "https://pi-tui.ratstack.sh/patterns/control-baton.md", "name": "Control Baton", "url": "https://pi-tui.ratstack.sh/patterns/control-baton/" } ], "sampleCode": { "code": "// Action Sieve: derive valid choices from execution and control state.\nimport { getSelectListTheme } from \"@earendil-works/pi-coding-agent\";\nimport { SelectList, Text, type SelectItem } from \"@earendil-works/pi-tui\";\nimport type { PatternStory } from \"../../../src/pattern.ts\";\n\ntype ControlSnapshot = { execution: \"running\"; owner: \"agent\" | \"human\" } | { execution: \"exited\"; code: number };\nfunction validChoices(snapshot: ControlSnapshot): SelectItem[] {\n if (snapshot.execution === \"exited\") return [\n { value: \"resume\", label: \"Resume conversation\" },\n { value: \"output\", label: \"Inspect saved output\" },\n ];\n return [\n snapshot.owner === \"agent\"\n ? { value: \"takeover\", label: \"Take control\" }\n : { value: \"return\", label: \"Return to agent\" },\n { value: \"background\", label: \"Send to background\" },\n { value: \"stop\", label: \"Stop job\" },\n ];\n}\n\nexport const story: PatternStory = {\n id: \"action-sieve\", title: \"Action Sieve\", kind: \"component\",\n apis: [\"SelectList\", \"Text\"], rows: 10,\n states: [\n { id: \"running\", label: \"Running job\" },\n { id: \"human\", label: \"Human control\", steps: [{ type: \"action\", name: \"takeover\" }] },\n { id: \"exited\", label: \"Exited job\", steps: [{ type: \"action\", name: \"exit\" }] },\n ],\n setup({ tui, theme, action }) {\n let snapshot: ControlSnapshot = { execution: \"running\", owner: \"agent\" };\n let choices = new SelectList(validChoices(snapshot), 4, getSelectListTheme());\n let outcome = \"Choose an applicable action\";\n function rebuild(next: ControlSnapshot) {\n snapshot = next;\n choices = new SelectList(validChoices(snapshot), 4, getSelectListTheme());\n choices.onSelect = item => { outcome = \"Chosen: \" + item.label; tui.requestRender(); };\n outcome = \"Unavailable actions are omitted\";\n tui.requestRender();\n }\n rebuild(snapshot);\n action(\"takeover\", () => rebuild({ execution: \"running\", owner: \"human\" }));\n action(\"exit\", () => rebuild({ execution: \"exited\", code: 0 }));\n return {\n invalidate() { choices.invalidate(); },\n handleInput(data) { choices.handleInput(data); tui.requestRender(); },\n render(width) {\n const status = snapshot.execution === \"exited\"\n ? \"Exited · code \" + snapshot.code\n : \"Running · \" + snapshot.owner + \" control\";\n return [\n ...new Text(theme.fg(\"accent\", \"Build job · \" + status), 0, 0).render(width),\n \"\", ...choices.render(width), \"\",\n ...new Text(theme.fg(\"muted\", outcome), 0, 0).render(width),\n ...new Text(theme.fg(\"dim\", \"↑↓ choose · enter apply\"), 0, 0).render(width),\n ];\n },\n };\n },\n};\n", "lang": "ts", "path": "stories/patterns/behavioral/action-sieve.ts" }, "states": [ { "dont": false, "expectFail": [], "frames": [ { "alt": "Action Sieve, Running job state, 40 columns, dark theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/running-40-dark.fbfd4d40730b.webp", "theme": "dark", "w": 800, "width": 40 }, { "alt": "Action Sieve, Running job state, 40 columns, light theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/running-40-light.4c0a7ba49889.webp", "theme": "light", "w": 800, "width": 40 }, { "alt": "Action Sieve, Running job state, 60 columns, dark theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/running-60-dark.60d71f1902fa.webp", "theme": "dark", "w": 1200, "width": 60 }, { "alt": "Action Sieve, Running job state, 60 columns, light theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/running-60-light.ec1d84d535c5.webp", "theme": "light", "w": 1200, "width": 60 }, { "alt": "Action Sieve, Running job state, 80 columns, dark theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/running-80-dark.73ac084228f2.webp", "theme": "dark", "w": 1600, "width": 80 }, { "alt": "Action Sieve, Running job state, 80 columns, light theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/running-80-light.7b3c46c7b075.webp", "theme": "light", "w": 1600, "width": 80 }, { "alt": "Action Sieve, Running job state, 120 columns, dark theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/running-120-dark.d3d48db4b45c.webp", "theme": "dark", "w": 2400, "width": 120 }, { "alt": "Action Sieve, Running job state, 120 columns, light theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/running-120-light.37b4cd8a72ba.webp", "theme": "light", "w": 2400, "width": 120 } ], "how": "Show takeover and background choices for a live synthetic job.", "id": "running", "label": "Running job", "problems": [] }, { "dont": false, "expectFail": [], "frames": [ { "alt": "Action Sieve, Human control state, 40 columns, dark theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/human-40-dark.15eccdfc8a69.webp", "theme": "dark", "w": 800, "width": 40 }, { "alt": "Action Sieve, Human control state, 40 columns, light theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/human-40-light.bf68be861c36.webp", "theme": "light", "w": 800, "width": 40 }, { "alt": "Action Sieve, Human control state, 60 columns, dark theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/human-60-dark.2119e3ce14bf.webp", "theme": "dark", "w": 1200, "width": 60 }, { "alt": "Action Sieve, Human control state, 60 columns, light theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/human-60-light.47808eb82082.webp", "theme": "light", "w": 1200, "width": 60 }, { "alt": "Action Sieve, Human control state, 80 columns, dark theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/human-80-dark.f11718cd10ae.webp", "theme": "dark", "w": 1600, "width": 80 }, { "alt": "Action Sieve, Human control state, 80 columns, light theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/human-80-light.46b8b726cd85.webp", "theme": "light", "w": 1600, "width": 80 }, { "alt": "Action Sieve, Human control state, 120 columns, dark theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/human-120-dark.b724b23e422d.webp", "theme": "dark", "w": 2400, "width": 120 }, { "alt": "Action Sieve, Human control state, 120 columns, light theme, 8 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 352, "rows": 8, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/human-120-light.43445555e46c.webp", "theme": "light", "w": 2400, "width": 120 } ], "how": "Show return-to-agent only while the human owns control.", "id": "human", "label": "Human control", "problems": [] }, { "dont": false, "expectFail": [], "frames": [ { "alt": "Action Sieve, Exited job state, 40 columns, dark theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/exited-40-dark.cffba593787a.webp", "theme": "dark", "w": 800, "width": 40 }, { "alt": "Action Sieve, Exited job state, 40 columns, light theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/exited-40-light.e0c2ec6f16e6.webp", "theme": "light", "w": 800, "width": 40 }, { "alt": "Action Sieve, Exited job state, 60 columns, dark theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/exited-60-dark.fd08d28ba532.webp", "theme": "dark", "w": 1200, "width": 60 }, { "alt": "Action Sieve, Exited job state, 60 columns, light theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/exited-60-light.294906a0f287.webp", "theme": "light", "w": 1200, "width": 60 }, { "alt": "Action Sieve, Exited job state, 80 columns, dark theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/exited-80-dark.265ae469d384.webp", "theme": "dark", "w": 1600, "width": 80 }, { "alt": "Action Sieve, Exited job state, 80 columns, light theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/exited-80-light.26e01273b317.webp", "theme": "light", "w": 1600, "width": 80 }, { "alt": "Action Sieve, Exited job state, 120 columns, dark theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/exited-120-dark.efedf9806b32.webp", "theme": "dark", "w": 2400, "width": 120 }, { "alt": "Action Sieve, Exited job state, 120 columns, light theme, 7 rows", "animated": false, "animation": null, "checks": [ { "evidence": [], "name": "width", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "style-leak", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "hard-coded-colour", "status": "pass", "verdict": "pass" }, { "evidence": [], "name": "height", "status": "pass", "verdict": "pass" } ], "h": 308, "rows": 7, "still": "https://pi-tui.ratstack.sh/frames/action-sieve/exited-120-light.bbc8f8845afe.webp", "theme": "light", "w": 2400, "width": 120 } ], "how": "Replace live controls with applicable completion choices.", "id": "exited", "label": "Exited job", "problems": [] } ], "structure": "execution + control state\n -> valid choices\nchoice -> action", "thumbnails": { "dark": { "animation": null, "src": "https://pi-tui.ratstack.sh/thumbs/action-sieve/dark.87c68418c586.webp" }, "light": { "animation": null, "src": "https://pi-tui.ratstack.sh/thumbs/action-sieve/light.405a5fbd4533.webp" } }, "url": "https://pi-tui.ratstack.sh/patterns/action-sieve/", "widths": [ 40, 60, 80, 120 ] }