{"_id":"@codecell-germany/agent-workflow-gui-skill","name":"@codecell-germany/agent-workflow-gui-skill","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@codecell-germany/agent-workflow-gui-skill","version":"0.1.0","private":false,"description":"Skill and local runtime pattern that teaches agents how to add observer GUIs and Human-in-the-Loop review to their own workflows","keywords":["agent","workflow","workflow-gui","observer-gui","runtime","human-in-the-loop","codex-skill","cli"],"license":"MIT","author":{"name":"Nikolas Gottschol"},"repository":{"type":"git","url":"git+https://github.com/codecell-germany/agent-workflow-gui-skill.git"},"homepage":"https://github.com/codecell-germany/agent-workflow-gui-skill#readme","bugs":{"url":"https://github.com/codecell-germany/agent-workflow-gui-skill/issues"},"bin":{"agent-flow":"dist/index.js","agent-flow-skill":"dist/installer.js"},"scripts":{"clean":"node scripts/clean.js","build":"npm run clean && tsc -p tsconfig.json && node scripts/copy-static.js && node scripts/ensure-executable.js","typecheck":"tsc --noEmit","test":"vitest run tests/unit","test:unit":"vitest run tests/unit","test:release":"node scripts/release-smoke.mjs","prepack":"npm run build && npm run test"},"publishConfig":{"access":"public"},"engines":{"node":">=25"},"dependencies":{"commander":"^14.0.1"},"devDependencies":{"@types/node":"^25.2.3","typescript":"^5.9.2","vitest":"^4.0.7"},"gitHead":"3be8ea604af80dbf6f67aca7a47a4888811f3a52","_id":"@codecell-germany/agent-workflow-gui-skill@0.1.0","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-zWBzHH7WDd52/vd4fBx0kQjhQSdnyss61gRicxWGeqYyw+ia2aNQ4U3sE1PKhi+58gUgJMBhHI0uCoM3mi1OSA==","shasum":"ee82da6bcbd4ac1d9be6b72b93ef0a5cc2e1ddce","tarball":"https://registry.npmjs.org/@codecell-germany/agent-workflow-gui-skill/-/agent-workflow-gui-skill-0.1.0.tgz","fileCount":32,"unpackedSize":133139,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDvZk6GotgNgrw2igbuZ+LupOe7WZ1y1cd4MLPmde69aQIgeFnNzl60aje/c06ELBalutZDBEzvT/qiwRBviPzYB2U="}]},"_npmUser":{"name":"codecell-germany","email":"admin@codecell.de"},"directories":{},"maintainers":[{"name":"codecell-germany","email":"admin@codecell.de"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-workflow-gui-skill_0.1.0_1776782386274_0.6177961795603173"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-21T14:39:46.198Z","0.1.0":"2026-04-21T14:39:46.408Z","modified":"2026-04-21T14:39:46.563Z"},"maintainers":[{"name":"codecell-germany","email":"admin@codecell.de"}],"description":"Skill and local runtime pattern that teaches agents how to add observer GUIs and Human-in-the-Loop review to their own workflows","homepage":"https://github.com/codecell-germany/agent-workflow-gui-skill#readme","keywords":["agent","workflow","workflow-gui","observer-gui","runtime","human-in-the-loop","codex-skill","cli"],"repository":{"type":"git","url":"git+https://github.com/codecell-germany/agent-workflow-gui-skill.git"},"author":{"name":"Nikolas Gottschol"},"bugs":{"url":"https://github.com/codecell-germany/agent-workflow-gui-skill/issues"},"license":"MIT","readme":"# Agent Workflow GUI Skill\n\nSkill, CLI and local runtime pattern that teaches agents how to wrap their own workflows with a live observer GUI and Human-in-the-Loop review.\n\n## What It Is\n\n`agent-flow` is not just a runtime for one specific workflow.\nIt is the reusable kernel an agent can use when it already has a workflow and wants to add a fixed GUI/HITL system around it.\n\nThe product provides:\n\n- a public CLI for runs, stages, artifacts and review tasks\n- a local SQLite runtime as shared truth\n- a read-mostly browser GUI shell with run selector, stage stepper, artifacts, events and HITL cards\n- a controlled Human-in-the-Loop approval path back into the workflow\n- a Codex skill that teaches agents how to structure and expose their own workflows through this system\n\nIn short:\n\n- your domain workflow stays yours\n- `agent-flow` provides the reusable run model, GUI pattern, event model and HITL bridge around it\n\n## Install\n\n### Local pre-publish verification\n\nWenn das Paket noch nicht veröffentlicht ist, nutze den lokale-Tarball-Weg:\n\n```bash\nnpm pack\nTMP=$(mktemp -d)\nCODEX_HOME=\"$TMP/codex\" npx -y -p ./codecell-germany-agent-workflow-gui-skill-<version>.tgz agent-flow-skill install --force\n\"$TMP/codex/bin/agent-flow\" --help\n```\n\n### Global npm install after publish\n\n```bash\nnpm install -g @codecell-germany/agent-workflow-gui-skill\nagent-flow --help\n```\n\n### One-shot with npx after publish\n\n```bash\nnpx -y -p @codecell-germany/agent-workflow-gui-skill agent-flow --help\n```\n\n### Install into Codex\n\n```bash\nnpx -y -p @codecell-germany/agent-workflow-gui-skill agent-flow-skill install --force\n~/.codex/bin/agent-flow --help\n```\n\nStandardziel ist `~/.codex`.\nDu kannst das Ziel mit `CODEX_HOME` oder `--codex-home` überschreiben.\nDie lokale Runtime selbst liegt standardmäßig unter `~/.agent-flow` und kann mit `AGENT_FLOW_HOME` oder `--runtime-home` überschrieben werden.\nEine Runtime kann bereits als `ready` gelten, obwohl `doctor --json` noch `dbExists: false` meldet. Die SQLite-Datei wird erst beim ersten echten Lauf angelegt.\n\n### Check skills.sh discovery locally\n\n```bash\nnpx -y skills add codecell-germany/agent-workflow-gui-skill -l\n```\n\n## First Run\n\n1. Check the public CLI:\n\n```bash\nagent-flow --help\n```\n\n2. Inspect system readiness:\n\n```bash\nagent-flow doctor --json\n```\n\n3. If setup is required, initialize the runtime:\n\n```bash\nagent-flow setup --language de\n```\n\n4. Verify again:\n\n```bash\nagent-flow doctor --json\n```\n\n5. Start the local GUI on the default port `4189`:\n\n```bash\nagent-flow serve\n```\n\nThe default GUI shell contains the reusable surface every workflow should start from:\n\n- a top header for the workflow GUI identity\n- an active-run dropdown for switching between runs\n- a horizontal stage stepper that shows pending, running, completed and failed states\n- a run detail area for stages, Human-in-the-Loop tasks, artifacts and events\n\nDomain-specific UIs should extend below this shell and keep the shell behavior intact.\n\n6. Create a run:\n\n```bash\nagent-flow run create --flow generic-observer-v1 --input-file /absolute/path/to/run-input.json\n```\n\n## Quick Start\n\nThink of this as the smallest possible example of how an agent workflow becomes GUI-visible.\n\nCreate a run input file:\n\n```json\n{\n  \"title\": \"Beispiel-Lauf\",\n  \"description\": \"Allgemeiner Agentenlauf mit Review-Schritt\",\n  \"context\": {\n    \"operator\": \"demo\"\n  }\n}\n```\n\nThen:\n\n```bash\nagent-flow run create --flow generic-observer-v1 --input-file ./run-input.json\nagent-flow run list --json\nagent-flow run show --run-id <run-id> --json\n```\n\nMinimal task file:\n\n```json\n{\n  \"taskType\": \"review.approval\",\n  \"subjectRef\": \"artifact:demo\",\n  \"promptText\": \"Freigeben?\",\n  \"responseSchema\": {\n    \"kind\": \"enum-with-comment\",\n    \"decisions\": [\"approve\", \"reject\"],\n    \"allowComment\": true\n  }\n}\n```\n\nMinimal answer file:\n\n```json\n{\n  \"decisionValue\": \"approve\",\n  \"commentText\": \"Passt.\",\n  \"expectedTaskVersion\": 1,\n  \"capabilityToken\": \"<aus run show oder task list>\",\n  \"idempotencyKey\": \"answer-001\",\n  \"actorId\": \"human.cli\"\n}\n```\n\nStart the first stage:\n\n```bash\nagent-flow stage start \\\n  --run-id <run-id> \\\n  --stage-instance-id <stage-instance-id> \\\n  --session-id agent-main \\\n  --expected-revision <revision>\n```\n\nOhne ein vorheriges `stage start` darf kein Human-in-the-Loop-Task für diese Stage erzeugt oder später abgeschlossen werden.\n\nCreate a Human-in-the-Loop task:\n\n```bash\nagent-flow task create \\\n  --run-id <run-id> \\\n  --stage-instance-id <stage-instance-id> \\\n  --session-id agent-main \\\n  --expected-revision <revision> \\\n  --task-file ./task.json\n```\n\nAnswer it either in the browser GUI or through the CLI:\n\n```bash\nagent-flow task answer \\\n  --run-id <run-id> \\\n  --task-id <task-id> \\\n  --answer-file ./answer.json\n```\n\nDann:\n\n```bash\nagent-flow run resume \\\n  --run-id <run-id> \\\n  --session-id agent-main \\\n  --expected-revision <revision>\n\nagent-flow stage complete \\\n  --run-id <run-id> \\\n  --stage-instance-id <stage-instance-id> \\\n  --session-id agent-main \\\n  --expected-revision <revision>\n```\n\nTypische Revisionskette für einen frischen HITL-Lauf:\n\n- `run create` -> Revision `0`\n- `stage start` -> Revision `1`\n- `task create` -> Revision `2`\n- `task answer` -> Revision `3`\n- `run resume` -> Revision `4`\n- `stage complete` -> Revision `5`\n\n## Public CLI Surface\n\nThe CLI is the public product surface an agent should build on top of.\nIt is the contract for turning a private workflow into a GUI-observable workflow.\n\n### Product commands\n\n- `agent-flow setup`\n- `agent-flow doctor`\n- `agent-flow serve`\n\n### Run commands\n\n- `agent-flow run create`\n- `agent-flow run list`\n- `agent-flow run show`\n- `agent-flow run status`\n- `agent-flow run resume`\n\n### Stage commands\n\n- `agent-flow stage list`\n- `agent-flow stage start`\n- `agent-flow stage progress`\n- `agent-flow stage checkpoint`\n- `agent-flow stage complete`\n- `agent-flow stage fail`\n\n### Artifact commands\n\n- `agent-flow artifact ingest`\n- `agent-flow artifact list`\n\n### Human-in-the-Loop commands\n\n- `agent-flow task create`\n- `agent-flow task list`\n- `agent-flow task wait`\n- `agent-flow task answer`\n\n## Security Model\n\nV1 is local and single-writer.\n\n- `agent-flow serve` binds to `127.0.0.1` by default\n- the browser is read-mostly\n- the only browser write is `task answer`\n- task answers require:\n  - task capability token\n  - expected task version\n  - idempotency key\n  - local CSRF header\n- artifacts are ingested into runtime-controlled paths only\n- no external URLs are registered as artifacts in V1\n\n## Codex Skill\n\nThe skill lives at:\n\n- `skills/agent-workflow-gui/SKILL.md`\n\nIts job is not only to explain the commands.\nIts job is to teach another agent how to expose its own workflow through the same run, stage, event, artifact and HITL pattern.\n\nIt defines:\n\n- when the runtime should be used\n- how first-run detection works\n- the canonical onboarding order\n- guardrails for agents\n- references for the HITL contract and command surface\n\n## Release Checks\n\nBefore release:\n\n```bash\nnpm run build\nnpm run test:unit\nnpm pack\nnpm run test:release\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-f807ff0db6fedd5255bc6262f851c647"}