@dna113p/machines 0.1.0

package/docs/integrations.md

@@ -0,0 +1,142 @@
+# Integrations
+
+## Codex through direct MCP
+
+From an arbitrary checkout, build and register the server:
+
+```bash
+npm ci
+npm run build
+codex mcp add machines -- node "$PWD/dist/mcp/server.js"
+```
+
+This command records the current checkout's absolute built entry point. Keep that
+checkout available, or register again after moving it. It requires no marketplace
+or helper skill. Start a new Codex thread and ask “Show me the Machines available
+here.” The [official MCP guide](https://developers.openai.com/codex/mcp) describes
+stdio server registration and configuration.
+
+The five tools are:
+
+| Tool | Inputs and result |
+| --- | --- |
+| `machine_list` | Absolute `cwd`; definitions, descriptions, missing Agents, per-file errors |
+| `machine_agents` | Absolute `cwd`; configured Agent preset names and metadata |
+| `machine_start` | Absolute `cwd`, Machine name, optional input/preset overrides; immediate run snapshot |
+| `machine_status` | Optional exact `runId`; authoritative current-session snapshots |
+| `machine_respond` | Exact `runId`, current `human.requestId`, and response; submits one waiting request |
+
+Preserve the IDs returned by the tools. A stale request or repeated submission is
+rejected. When explicit choices are present, send one of those exact strings.
+
+Codex CLI can use text and structured tool results. Clients supporting MCP Apps
+can also render the attached live card, which polls status and submits Human input.
+Client support for the card varies; the same tools work without it.
+
+## Portable Codex plugin
+
+Build the self-contained plugin from the checkout:
+
+```bash
+npm ci
+npm run build:plugin
+npm run smoke:plugin
+```
+
+The result is `build/codex/machines/`, containing the manifest, compiled server,
+production dependencies, widget assets, and machine-builder skill. Copy the entire
+directory when distributing it. Node 24 or later must be on the receiving system's
+PATH; the original checkout is unnecessary after copying. Build does not modify
+your Codex installation or global configuration.
+
+The plugin MCP configuration uses `command: "node"`, a relative server argument,
+and `cwd: "."`. Codex resolves the plugin's relative working directory against
+the installed plugin root, so no checkout-specific path or shell expansion is
+needed. The source `codex/machines/` directory is an input to this build, not the
+complete installable bundle.
+This path behavior is implemented by the
+[Codex 0.153.2 plugin parser](https://github.com/openai/codex/blob/rust-v0.153.2/codex-rs/codex-mcp/src/plugin_config.rs#L281-L288).
+
+Install the resulting directory through your chosen local/repository marketplace
+using the [official plugin packaging guide](https://developers.openai.com/plugins/build/plugins#install-a-local-plugin-manually).
+For example, copy the complete bundle to a marketplace repository's
+`plugins/machines/`, and add this entry to its `.agents/plugins/marketplace.json`:
+
+```json
+{
+  "name": "machines-local",
+  "interface": { "displayName": "Machines local" },
+  "plugins": [{
+    "name": "machines",
+    "source": { "source": "local", "path": "./plugins/machines" },
+    "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
+    "category": "Productivity"
+  }]
+}
+```
+
+From that marketplace root, the current Codex CLI accepts:
+
+```bash
+codex plugin marketplace add "$PWD"
+codex plugin add machines@machines-local
+```
+
+Existing marketplaces can add the plugin entry to their current list instead of
+replacing their catalog. Use the direct MCP route when a marketplace is unnecessary.
+Choose one installation route per Codex environment to avoid duplicate tools.
+
+After updating the build, replace the complete bundle in the marketplace and
+refresh the installation using the host's plugin management controls. Start a new
+thread after installing or updating. The plugin version comes from its checked-in
+manifest; release changes should bump it along with the package version.
+
+The bundled configuration pre-approves the launcher tools. Discovery imports
+trusted code, and start/respond can continue work that modifies files or contacts
+external services. Tool annotations describe those capabilities. Configure your
+preferred tool-approval policy in Codex if you need different behavior; workflow
+Human states remain defined by each Machine.
+
+## Pi extension
+
+For a checkout on POSIX systems:
+
+```bash
+mkdir -p ~/.pi/agent/extensions
+ln -s "$PWD/pi-extension/index.ts" ~/.pi/agent/extensions/machines.ts
+```
+
+Run this from the Machines checkout after `npm ci`. Choose an unused destination;
+the command does not replace an existing extension. Pi discovers it on startup;
+use `/reload` after a source update. Keep the checkout available while using the
+symlink. A locally installed npm package also includes the built extension at
+`node_modules/@dna113p/machines/dist/pi-extension/index.js`.
+
+Pi exposes the same five tools using the conversation's current directory, with
+a status widget and native Human dialogs. Canceling a dialog leaves its Machine
+waiting; answer later through `machine_respond` with the current request ID.
+Pi exit, session replacement, and reload terminate its session-owned runs.
+
+## Troubleshooting
+
+For an isolated global catalog, set `MACHINES_USER_HOME` to an absolute directory;
+Machines reads global definitions and presets from that directory's `.machines/`.
+Explicit programmatic `home` options take precedence. This is useful for tests or
+separate workflow collections without changing the operating-system home directory.
+
+- **Node cannot load TypeScript from a dependency:** install the built tarball;
+  source exports are for checkout development. Keep workflow definitions outside
+  `node_modules` and use Node 24 or later.
+- **A definition has an error or missing Agent:** inspect `machine list` and
+  `machine agents`, correct metadata or presets, and list again. Imports refresh
+  on the next discovery call. Run preflight remains strict.
+- **The Agent fails on a permission request:** ACP permission interaction is not
+  implemented. Use a harness configured for the intended task; Human states
+  handle workflow decisions, not ACP permission prompts.
+- **A run disappeared after reload:** runs are session-scoped and have no durable
+  resume mechanism. Inspect effects already produced before starting another run.
+- **The Codex card is absent:** use `machine_status` and `machine_respond`; visual
+  resource rendering depends on the MCP client.
+- **Agent output is too noisy:** ACP callers can select `output: "capture"`;
+  the launcher already captures final text. The CLI's `o` hotkey toggles normalized
+  activity while an Agent runs and is suspended during Human input.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@dna113p/machines",
+  "version": "0.1.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" },
+    "./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" }
+  },
+  "files": ["dist", "docs/architecture.md", "docs/authoring.md", "docs/integrations.md", "skills", "LICENSE", "README.md"],
+  "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: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"
+  }
+}

package/skills/machine-builder/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: machine-builder
+description: Create or edit TypeScript workflow definitions for the Machines runtime, including discovery metadata, Agent roles, Operations, Human decisions, and transitions. Use for reusable Machines workflows, not unrelated XState applications or runtime internals.
+---
+
+# Machine builder
+
+Use [Authoring Machines](../../docs/authoring.md) for the definition contract and
+examples. Before choosing a workflow, inspect available Machines and Agent presets
+with `machine list` and `machine agents`, or the connected `machine_list` and
+`machine_agents` tools. Adapt a matching workflow when it fits the user's scope.
+
+For a new definition, capture the intended states, returned events, and completion
+condition. Put the definition in the requested location; project `.machines/` is
+the default for project-specific work. Global installation is a separate choice.
+
+Export a non-empty one-line `description` explaining when to use the Machine and
+a default factory accepting the supplied primitives and input string. Declare
+semantic `agentRoles` for named Agents, then use those exact roles in states.
+Select harnesses and models through presets, keeping environment details out of
+workflow policy. The [bundled examples](../../dist/examples/) show runtime usage
+after the package is built; authoring examples in the guide also work before a build.
+
+Keep module initialization side-effect free: discovery imports definitions and
+their helpers. Put external work inside Operations or Agent requests so preflight
+can finish before effects occur. Let XState choose the next state from the event
+returned by a primitive. Use Human `suggestions` when free-form feedback is useful
+and `choices` when only the declared responses are valid.
+
+Verify discovery and bindings, then exercise the intended branches with fake
+Agent runners or injected Human input where possible. A successful run reaches
+the intended final state and produces the requested artifact or effect. Run real
+external work only within the user's authorized scope. Report what was verified
+and any branch that still requires a configured harness or human interaction.