{"_id":"@dna113p/machines","_rev":"2-e0f904d96c16875213cd257cc9a178c1","name":"@dna113p/machines","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@dna113p/machines","version":"0.1.0","license":"MIT","_id":"@dna113p/machines@0.1.0","maintainers":[{"name":"dna113p","email":"djpelland@gmail.com"}],"homepage":"https://github.com/dna113p/machines#readme","bugs":{"url":"https://github.com/dna113p/machines/issues"},"bin":{"machine":"dist/src/cli.js"},"dist":{"shasum":"f37e58333a012a97764c684544b75a3af79b98fc","tarball":"https://registry.npmjs.org/@dna113p/machines/-/machines-0.1.0.tgz","fileCount":50,"integrity":"sha512-7UuuJTdR/afXFNXkUe8rdBd7Oz7VYYS7qsVXWrdVnwUWmr2VLnGTKkuRNaPq07FtnZnVgTh2DjzD7CKeHxJ7aw==","signatures":[{"sig":"MEUCIQCrUZkhFteOLwlxznJ53hXfelUU1ECYC0JZJcvB+0ySkwIgWV5tFmonViBe/DrckPIoFvQJTUBB4Wbamxo60UwyJdU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":184902},"type":"module","_from":"file:/tmp/machines-npm-release-b6gqzmin/dna113p-machines-0.1.0.tgz","types":"./dist/src/index.d.ts","engines":{"node":">=24"},"exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"},"./acp":{"types":"./dist/src/acp.d.ts","import":"./dist/src/acp.js"},"./mcp":{"types":"./dist/mcp/server.d.ts","import":"./dist/mcp/server.js"},"./launcher":{"types":"./dist/src/launcher.d.ts","import":"./dist/src/launcher.js"},"./pi-extension":{"types":"./dist/pi-extension/index.d.ts","import":"./dist/pi-extension/index.js"}},"scripts":{"mcp":"node mcp/server.ts","test":"node --test tests/*.test.ts","build":"node scripts/build.mjs","check":"npm run typecheck && npm test","example":"node examples/operation.ts","prepack":"npm run build","typecheck":"tsc --noEmit","example:pi":"node examples/pi.ts","build:plugin":"npm run build && node scripts/build-plugin.mjs","example:host":"node examples/host.ts","smoke:plugin":"node scripts/smoke-plugin.mjs","smoke:package":"node scripts/smoke-package.mjs","example:agents":"node examples/named-agents.ts"},"_npmUser":{"name":"dna113p","email":"djpelland@gmail.com"},"_resolved":"/tmp/machines-npm-release-b6gqzmin/dna113p-machines-0.1.0.tgz","_integrity":"sha512-7UuuJTdR/afXFNXkUe8rdBd7Oz7VYYS7qsVXWrdVnwUWmr2VLnGTKkuRNaPq07FtnZnVgTh2DjzD7CKeHxJ7aw==","repository":{"url":"git+https://github.com/dna113p/machines.git","type":"git"},"_npmVersion":"11.17.0","description":"Reusable workflows coordinating agents, local operations, and human decisions.","directories":{},"_nodeVersion":"24.19.0","dependencies":{"xstate":"^5.32.6","typebox":"^1.3.7","valibot":"^1.4.2","yoctocolors":"^2.2.0","yocto-spinner":"^1.2.2","@agentclientprotocol/sdk":"^1.4.0","@modelcontextprotocol/sdk":"^1.30.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^7.0.2","@types/node":"^24.0.0"},"_npmOperationalInternal":{"tmp":"tmp/machines_0.1.0_1788638960667_0.04883129930171681","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@dna113p/machines","version":"0.2.0","description":"Reusable workflows coordinating agents, local operations, and human decisions.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/dna113p/machines.git"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"type":"module","engines":{"node":">=24"},"bin":{"machine":"dist/src/cli.js"},"types":"./dist/src/index.d.ts","exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"},"./acp":{"types":"./dist/src/acp.d.ts","import":"./dist/src/acp.js"},"./agy":{"types":"./dist/src/agy.d.ts","import":"./dist/src/agy.js"},"./launcher":{"types":"./dist/src/launcher.d.ts","import":"./dist/src/launcher.js"},"./mcp":{"types":"./dist/mcp/server.d.ts","import":"./dist/mcp/server.js"},"./pi-extension":{"types":"./dist/pi-extension/index.d.ts","import":"./dist/pi-extension/index.js"}},"scripts":{"build":"node scripts/build.mjs","build:plugin":"npm run build && node scripts/build-plugin.mjs","check":"npm run typecheck && npm test","example":"node examples/operation.ts","example:agents":"node examples/named-agents.ts","example:agy":"node examples/agy.ts","example:host":"node examples/host.ts","example:pi":"node examples/pi.ts","mcp":"node mcp/server.ts","prepack":"npm run build","smoke:package":"node scripts/smoke-package.mjs","smoke:plugin":"node scripts/smoke-plugin.mjs","test":"node --test tests/*.test.ts","typecheck":"tsc --noEmit"},"dependencies":{"@agentclientprotocol/sdk":"^1.4.0","@modelcontextprotocol/sdk":"^1.30.0","typebox":"^1.3.7","valibot":"^1.4.2","xstate":"^5.32.6","yocto-spinner":"^1.2.2","yoctocolors":"^2.2.0"},"devDependencies":{"@types/node":"^24.0.0","typescript":"^7.0.2"},"gitHead":"e5ebfab1dd20bae9c47e28792c10e504f8a8ea83","_id":"@dna113p/machines@0.2.0","bugs":{"url":"https://github.com/dna113p/machines/issues"},"homepage":"https://github.com/dna113p/machines#readme","_nodeVersion":"24.20.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-1PxJ5aOl7XuUcy6Gb20IsXZyGB72KCjNSDo7SDJ+3kqdJrGVHU+Smku+tPt7GEB2aCEWEjbbOO/YGKLv5ihrJw==","shasum":"7b2e77fef9cfa7fd8d3d810798b9d7a046284e41","tarball":"https://registry.npmjs.org/@dna113p/machines/-/machines-0.2.0.tgz","fileCount":56,"unpackedSize":197031,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dna113p%2fmachines@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCkmJHDzlrxYCb5iV+lAhtvr1IAuPhiXgvtC9sJ1t5ytQIgCJQeZLvGM/4eAps5sVOex4RD27le+tofaGVA8Q19+GY="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:54e0bc4d-7555-49a6-bed7-1ffecc9948c5"}},"directories":{},"maintainers":[{"name":"dna113p","email":"djpelland@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/machines_0.2.0_1788700516937_0.274599070842362"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-05T20:09:20.563Z","modified":"2026-09-06T13:15:17.449Z","0.1.0":"2026-09-05T20:09:20.794Z","0.2.0":"2026-09-06T13:15:17.078Z"},"bugs":{"url":"https://github.com/dna113p/machines/issues"},"license":"MIT","homepage":"https://github.com/dna113p/machines#readme","repository":{"type":"git","url":"git+https://github.com/dna113p/machines.git"},"description":"Reusable workflows coordinating agents, local operations, and human decisions.","maintainers":[{"name":"dna113p","email":"djpelland@gmail.com"}],"readme":"# Machines\n\nReusable workflows that coordinate agents, local operations, and human decisions.\n\nA Machine makes a repeatable process explicit: ask an Agent to implement a change,\nrun an Operation to check it, and ask a Human to approve or provide feedback. Each\nstate returns an event; the Machine decides what happens next. XState handles the\ntransitions, while the same workflow can run from a terminal, Pi, or Codex.\n\n```text\nimplement (Agent) → check (Operation) → review (Human) → done\n        ↑                                  │\n        └──────────── feedback ────────────┘\n```\n\nUse Machines when a sequence and its decision points are worth repeating. A\none-off prompt or shell script remains useful for work that needs no workflow.\n\n## Quickstart\n\nRequires **Node.js 24 or later** and npm. From a checkout of this repository:\n\n```bash\nnpm ci\nnpm run check\nnpm run example\n```\n\nThe deterministic example needs no credentials or Agent installation and prints:\n\n```text\ncalculate --completed--> done\n```\n\nHere is its complete implementation, runnable as `demo.ts` in the checkout root:\n\n```ts\nimport { final, machine, operation, run } from \"./src/index.ts\";\n\nconst workflow = machine({\n  initial: \"calculate\",\n  states: {\n    calculate: operation(\n      () => ({ type: \"completed\" }),\n      { completed: \"done\" },\n    ),\n    done: final(),\n  },\n});\n\nconst result = await run(workflow);\nconsole.log(`calculate --completed--> ${String(result.value)}`);\n```\n\nRun it with `node demo.ts`. No build is needed to develop against the source.\n\n| Example | Command | Requirements |\n| --- | --- | --- |\n| Deterministic Operation | `npm run example` | Node only |\n| Human input | `node examples/human.ts` | Terminal input |\n| Suggestions and choices | `node examples/choices.ts` | Terminal input |\n| Agent contract | `node examples/agent.ts` | Built-in fake runner |\n| Agent escalation | `npm run example:agents` | Built-in fake runners |\n| Child host and Human response | `npm run example:host` | Node only |\n| Real Agent writes and verifies a file | `npm run example:pi` | Configured Pi through `pi-acp`; may use network and model credits |\n| Real AGY writes and verifies a file | `npm run example:agy` | Configured Antigravity CLI (`agy`); may use network and model credits |\n\n## Run your own workflows\n\nSave this as `.machines/hello.ts` in your project:\n\n```ts\nimport type { MachinePrimitives } from \"@dna113p/machines\";\n\nexport const description = \"Prints the supplied message without an Agent.\";\n\nexport default function hello(\n  { machine, operation, final }: MachinePrimitives,\n  input: string,\n) {\n  return machine({\n    initial: \"print\",\n    states: {\n      print: operation(() => {\n        console.log(input || \"Hello from Machines.\");\n        return { type: \"completed\" };\n      }, { completed: \"done\" }),\n      done: final(),\n    },\n  });\n}\n```\n\nFrom the checkout, run:\n\n```bash\n./machine list\n./machine show hello\n./machine run hello \"Hello from Machines.\"\n```\n\nThe command reports the Machine path and state progress, then prints `--> done`.\nIn another project, use the checkout's absolute `machine` path or install the npm\npackage below. The `MachinePrimitives` import is type-only; executing this definition\nuses the primitives supplied by the launcher.\n\nDiscovery checks the nearest project `.machines/` and then `~/.machines/`.\nProject definitions replace global definitions with the same name. Files can be\n`name.ts` or `name/index.ts`; the single file wins if both exist. `agents.ts` is\nreserved for Agent presets. Invalid definitions remain visible with their own\ndiagnostics; other valid Machines remain usable.\n\nRead [Authoring Machines](docs/authoring.md) for Human input, Agent roles and\npresets, feedback loops, and the programmatic launcher.\n\n## Install from npm\n\nInstall the package in your project:\n\n```bash\nnpm install @dna113p/machines\nnpx machine list\n```\n\nOr run the CLI without adding a project dependency:\n\n```bash\nnpx @dna113p/machines list\n```\n\nThe command is still named `machine`. For a global installation, run\n`npm install --global @dna113p/machines`, then use `machine list` or `machine run`.\n\nTo install a build from a checkout instead:\n\n```bash\nnpm ci\nnpm pack\n```\n\nThen install the generated `dna113p-machines-0.1.0.tgz` into a project:\n\n```bash\nnpm install /absolute/path/to/machines/dna113p-machines-0.2.0.tgz\nnpx machine list\n```\n\nThe package contains JavaScript and TypeScript declarations. Application code can\nimport `{ machine, agent, human, operation, final, run }` from `\"@dna113p/machines\"`.\nWorkflow definitions remain ordinary TypeScript outside `node_modules`.\n\nFor **Codex MCP**, **the portable Codex plugin**, or **the Pi extension**, follow\n[Integrations](docs/integrations.md). No personal marketplace or developer-only\ninstallation script is required for the direct MCP setup.\n\n## Execution model and limitations\n\nMachine definitions and Agent preset files are **trusted executable code**.\nDiscovery imports them to inspect metadata, including their relative imports.\nKeep module initialization free of side effects and do work inside states.\nDisposable discovery workers refresh imported metadata; they are not a sandbox.\nOperations and configured Agents run with the launching process's available access\nand can modify files or contact external services.\n\nPi and MCP runs belong to the current session. Closing or reloading that session\nterminates its owned hosts; runs are not persisted or resumable. Process shutdown\ndoes not undo files or Git changes. A Machine owns its own retry, approval, merge,\nand cleanup decisions. See [Architecture](docs/architecture.md) for ownership and\nprocess-lifecycle limits.\n\nACP permission requests are currently unsupported and fail the Agent state. Choose\na harness configuration that can carry out the intended bounded task and put\nworkflow decisions in Human states. The launcher defaults unnamed Agents to\n`npx -y pi-acp`; [Agent presets](docs/authoring.md#agent-presets) let you select\nanother ACP command or runner explicitly.\n\nThe built-in `agy` preset selects the Antigravity CLI with AGY permission checks\nenabled. [AGY configuration](docs/authoring.md#antigravity-agy) explains runner\nsettings and explicit opt-in to automatic tool approval. `npm run example:agy`\nopts in for its temporary-directory demonstration.\n\n## Checks\n\n```bash\nnpm run check          # typecheck and behavior tests\nnpm run build          # JavaScript, declarations, examples, and UI assets\nnpm run smoke:package  # install a tarball in a temporary project and exercise it\nnpm run build:plugin\nnpm run smoke:plugin   # exercise a relocated standalone plugin\n```\n\n## Releasing\n\nThe [publishing workflow](.github/workflows/publish.yml) uses a standard GitHub\nrunner and npm trusted publishing, without an npm token stored in GitHub.\nPushing a `vX.Y.Z` tag runs the checks above and publishes to npm if they pass.\nThe tag must match the stable version in `package.json`.\n\nFor example, to release the next minor version from an up-to-date, clean `main`:\n\n```bash\nnpm version minor\ngit push origin main --follow-tags\n```\n\nRunning **Publish to npm** manually in GitHub Actions performs the checks and a\npublishing dry run; it does not publish a package.\n\nLicensed under the [MIT License](LICENSE).\n","readmeFilename":"README.md"}