iii-exec

iii-exec

The iii-exec worker runs a sequential pipeline of shell commands as part of engine startup. Each entry in the configured exec: array launches as a separate child process and must exit 0 before the next entry starts; the final entry is kept running as a long-lived process for the engine's lifetime. An optional watch: glob list restarts the whole pipeline whenever a matching file changes.

The worker exposes no callable functions and no trigger types — its surface is entirely declarative. There is nothing for an agent to call at runtime; configure exec: (and optionally watch:) on the worker and the engine manages the lifecycle, supervising and shutting the process down alongside itself.

When to Use

• The engine should manage the lifecycle of a separate long-running app or daemon (boot, supervise, shut down together).
• You need prep steps that must succeed in order before a long-lived server starts (for example, install then build then serve).
• During development, the pipeline should restart automatically when source files change (via watch:).

Boundaries

• Not a runtime command executor — the pipeline runs at engine startup only; there is no function to "run this command now."
• Not a scheduler — use the iii-cron trigger for recurring jobs; iii-exec is one-shot startup plus a single long-lived process.
• Entries run sequentially, not in parallel, and do not share working directory or environment; chain dependent steps with && inside one entry.
• A non-zero exit on any intermediate command stops the pipeline and the long-lived command never starts.

Configuration

• exec: string[] (required) — sequential pipeline of shell commands. Intermediate entries must exit 0; the final entry is held open as the long-lived process.
• watch: string[] (optional) — glob patterns that restart the whole pipeline on file change. Caveat: the watcher matches by root directory plus file extension only — the filename portion is ignored, so src/**/*.test.ts matches every .ts file under src/, not just test files. Files without an extension are never matched. Use ** for recursive depth (config/*.json watches only the top level; config/**/*.json watches at any depth).

- name: iii-exec
  config:
    watch:
      - steps/**/*.{ts,js}
    exec:
      - cd frontend && npm install
      - cd frontend && npm run build
      - bun run --enable-source-maps index-production.js

The first two commands run in order and must exit 0; the third stays running for the worker's lifetime. If a prep step fails, the pipeline stops and the engine surfaces the failure.