{"id":50139322,"url":"https://github.com/ctxr-dev/fsm","last_synced_at":"2026-05-24T00:05:36.834Z","repository":{"id":353946203,"uuid":"1221508258","full_name":"ctxr-dev/fsm","owner":"ctxr-dev","description":"FSM = Finite State Machine.  A formal model where the system is always in exactly one of a fixed set of \"states\", and moves between them via \"transitions\" that fire when specific predicates evaluate true.","archived":false,"fork":false,"pushed_at":"2026-04-26T11:00:45.000Z","size":84,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T12:24:21.546Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ctxr-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T10:02:18.000Z","updated_at":"2026-04-26T11:00:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ctxr-dev/fsm","commit_stats":null,"previous_names":["ctxr-dev/fsm"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ctxr-dev/fsm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctxr-dev%2Ffsm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctxr-dev%2Ffsm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctxr-dev%2Ffsm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctxr-dev%2Ffsm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ctxr-dev","download_url":"https://codeload.github.com/ctxr-dev/fsm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctxr-dev%2Ffsm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33416317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-24T00:05:35.963Z","updated_at":"2026-05-24T00:05:36.827Z","avatar_url":"https://github.com/ctxr-dev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `@ctxr/fsm`\n\nGeneric finite-state-machine substrate for deterministic LLM-orchestrated workflows.\n\nConsumers (skills, agents, CI workflows) declare a YAML state machine + worker prompt templates and call this package's CLIs to drive a run. The CLIs handle:\n\n- Atomic state writes (POSIX `O_EXCL` lock files with TTL; write-tmp+fsync+rename).\n- Date-sharded filesystem layout for any volume of runs (256 shards under each day).\n- JSON-Schema-validated worker outputs at every state boundary.\n- Safe deterministic-predicate DSL (no `eval`, no string interpolation).\n- Trace files capturing every transition with inputs / outputs / predicate evaluations.\n\nThe package is consumer-agnostic — no project-specific paths, no hardcoded state names. Configure via `--storage-root` / `--fsm-path` flags or a `.fsmrc.json` config file at the consumer's project root.\n\n## Status\n\n**v0.1 — foundations.** Stable interface for the four core CLIs. v0.2 adds lifecycle CLIs (resume, pause, abandon, pivot, stale-cleanup, validate-trace). See [`docs/orchestration-design.md`](docs/orchestration-design.md) for the full roadmap.\n\n## Install\n\nWhile the package is in early development, consumers reference it via a `file://` path to the sibling repo:\n\n```json\n{\n  \"dependencies\": {\n    \"@ctxr/fsm\": \"file:../fsm\"\n  }\n}\n```\n\nAfter publication to npm, consumers will use the standard semver form.\n\n## Quick start\n\n1. **Author an FSM YAML** at e.g. `fsm/my-orchestrator.fsm.yaml`. See [`docs/state-yaml-reference.md`](docs/state-yaml-reference.md) for the schema.\n\n2. **Author worker prompt templates** for each state with a `worker:` block. See [`docs/worker-contract.md`](docs/worker-contract.md).\n\n3. **Add a `.fsmrc.json`** at your project root. The `fsms[]` array supports any number of named FSMs (one per agent / logical pipeline):\n\n   ```json\n   {\n     \"fsms\": [\n       {\n         \"name\": \"code-review\",\n         \"fsm_path\": \"fsm/code-review.fsm.yaml\",\n         \"storage_root\": \".my-app/runs/code-review\"\n       },\n       {\n         \"name\": \"report-builder\",\n         \"fsm_path\": \"fsm/report-builder.fsm.yaml\",\n         \"storage_root\": \".my-app/runs/reports\"\n       }\n     ]\n   }\n   ```\n\n   The config file is static — only project-level setup. Runtime concerns like `session_id` are passed via CLI flags (`--session-id`) or auto-generated, never persisted in the config.\n\n4. **Validate the FSM**:\n\n   ```bash\n   npx fsm-validate-static fsm/my-orchestrator.fsm.yaml\n   ```\n\n5. **Drive a run** from your orchestrator. With one FSM in the config you can omit `--fsm`; with multiple FSMs you pass `--fsm \u003cname\u003e` to pick:\n\n   ```bash\n   # Start a new run (single-FSM config)\n   npx fsm-next --new-run --repo my-app --base-sha aaa --head-sha bbb --args '{\"some\":\"input\"}'\n\n   # Start a new run against a named FSM in a multi-FSM config\n   npx fsm-next --fsm code-review --new-run --repo my-app --base-sha aaa --head-sha bbb --args '{\"some\":\"input\"}'\n\n   # ...orchestrator dispatches workers, collects JSON outputs...\n\n   # Commit each state's output and advance\n   npx fsm-commit --fsm code-review --run-id \u003crun-id\u003e --outputs '{\"x\":42}'\n\n   # Inspect at any time\n   npx fsm-inspect --fsm code-review --run-id \u003crun-id\u003e\n   ```\n\n   You can always bypass the config by passing `--fsm-path` + `--storage-root` directly.\n\nThe CLIs all return JSON to stdout. Exit codes: `0` success, `1` runtime error (lock conflict, schema violation, etc.), `2` argument error.\n\n## Documentation\n\n- [`docs/orchestration-design.md`](docs/orchestration-design.md) — design substrate; failure-mode analysis; architecture; on-disk schemas; roadmap.\n- [`docs/cli-reference.md`](docs/cli-reference.md) — exhaustive CLI reference for `fsm-next`, `fsm-commit`, `fsm-inspect`, `fsm-validate-static`.\n- [`docs/state-yaml-reference.md`](docs/state-yaml-reference.md) — FSM YAML schema with examples.\n- [`docs/worker-contract.md`](docs/worker-contract.md) — worker prompt template conventions and JSON Schema response contract.\n- [`docs/storage-layout.md`](docs/storage-layout.md) — disk layout, lock semantics, manifest schema.\n\n## Programmatic API\n\nThe package's [`scripts/lib/index.mjs`](scripts/lib/index.mjs) re-exports the engine and helpers for consumers who want to embed the engine directly. The CLIs are the recommended interface — they handle the structured-emit protocol, atomic writes, and lock management for free.\n\n```js\nimport { evaluatePredicate, loadFsm, runEnv, resolveTransition } from \"@ctxr/fsm\";\n\nconst fsm = loadFsm({ fsmPath: \"fsm/my-orchestrator.fsm.yaml\" });\nconst env = runEnv(\"20260426-001512-a3f7c9b\", { storageRoot: \".my-app/runs\" });\nconst { transition } = resolveTransition(stateById(fsm.doc, \"my_state\"), env);\n```\n\n## Tests\n\n```bash\nnpm install\nnpm test\n```\n\nThe test suite covers the storage layer, predicate DSL, schema validators, static FSM validation, and the CLI runtime end-to-end.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctxr-dev%2Ffsm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fctxr-dev%2Ffsm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctxr-dev%2Ffsm/lists"}