runspool 0.1.0__tar.gz

runspool-0.1.0/.env.example

@@ -0,0 +1,9 @@
+# Runspool is local-first and needs no secrets to run.
+#
+# This file exists only as a convention for custom steps that you write and
+# that may need credentials (for example, a step that calls an external API).
+# Copy it to `.env` and load it however your steps prefer. Runspool itself
+# does not read `.env`; it never requires network access or API keys.
+#
+# Example (used only if YOU write a step that reads it):
+# MY_SERVICE_API_KEY=

runspool-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,48 @@
+---
+name: Bug report
+about: Report a problem with Runspool
+title: "[Bug] "
+labels: bug
+---
+
+Thanks for taking the time to report a bug. Please fill out the sections below so we can reproduce and fix the issue quickly.
+
+## Describe the bug
+
+A clear and concise description of what the bug is.
+
+## To reproduce
+
+Steps to reproduce the behavior:
+
+1. Initialize a workspace
+2. Add one or more steps
+3. Run the workflow
+4. Observe the error
+
+```bash
+runspool init
+runspool add build --cmd "make"
+runspool add test --cmd "pytest" --after build
+runspool run
+```
+
+## Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+## Actual behavior
+
+A clear and concise description of what actually happened. Where possible,
+include the output of `runspool inspect <id> --json` for the affected run or
+step so we can see the full state.
+
+## Environment
+
+- OS: (e.g. macOS 14.5, Ubuntu 22.04, Windows 11)
+- Python version: output of `python --version`
+- Runspool version: output of `runspool --help` (version line) or `pip show runspool`
+
+## Additional context
+
+Add any other context about the problem here (logs, config files, screenshots).

runspool-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

runspool-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: Feature request
+about: Suggest an idea for Runspool
+title: "[Feature] "
+labels: enhancement
+---
+
+## Problem
+
+A clear and concise description of the problem or limitation you are running
+into. What are you trying to accomplish?
+
+## Proposed solution
+
+A clear and concise description of what you want to happen.
+
+## Alternatives considered
+
+A clear and concise description of any alternative solutions or features you
+have considered.
+
+## Additional context
+
+Add any other context, examples, or references about the feature request here.
+
+---
+
+> **A note on scope:** Runspool is intentionally local-first and CLI-first. It
+> is not a cloud platform, not an AI product, and has no web UI. Please keep
+> proposals aligned with these non-goals; feature requests that depend on hosted
+> services, an AI engine, or a graphical interface are out of scope.

runspool-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+## Summary
+
+Briefly describe what this pull request changes and why.
+
+## Related issue
+
+Closes #(issue number), or link to the relevant issue / discussion.
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation
+- [ ] Refactor
+- [ ] Test
+
+## Checklist
+
+- [ ] `ruff check .` passes
+- [ ] `pytest` passes
+- [ ] Added or updated tests for the change
+- [ ] Updated documentation if needed
+- [ ] Follows the existing code style and keeps the engine local-first
+
+## Notes for reviewers
+
+Anything reviewers should pay special attention to (tricky areas, trade-offs,
+follow-up work).

runspool-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Test (pytest)
+        run: pytest
+
+      - name: Smoke-test examples
+        run: bash scripts/smoke_examples.sh

runspool-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build backend
+        run: python -m pip install --upgrade build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

runspool-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Runspool runtime state (local-first: never commit task data or databases)
+workspace/
+*.db
+*.db-journal
+*.db-wal
+.env
+
+# Ignore a config.yaml created at the repo root by `runspool init`, but keep the
+# committed example configs under examples/ (note the leading slash anchors this
+# to the repo root only).
+/config.yaml
+
+# Examples create their own local state
+examples/**/workspace/
+examples/**/runspool.db
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+*.swp

runspool-0.1.0/AGENTS.md

@@ -0,0 +1,30 @@
+# Notes for AI agents and automation
+
+Runspool is designed to be driven by automated callers. This file is a quick
+orientation; see [docs/agent-json-output.md](docs/agent-json-output.md) for the
+full schema.
+
+## The loop
+
+1. Queue work: `runspool add <input> --workflow <name>`
+2. Advance it: `runspool run` (one-shot) or `runspool daemon` (resident)
+3. Read state: `runspool inspect <id> --json`
+4. Decide from the result:
+   - `status: "completed"` → done; artifacts are listed in `artifacts`.
+   - `status: "manual_required"` → read `last_error` and
+     `suggested_next_action`, fix the cause, then run the suggested command
+     (often `runspool retry <id>`), and advance again.
+   - `status: "running"` / `"queued"` → wait and poll again.
+
+## Rules of thumb
+
+- Use `--json` on every read command; never parse human-formatted output.
+- Choose actions only from the task's `available_actions`.
+- `inspect`'s `suggested_next_action` already encodes the recommended recovery.
+- Treat `completed` and `terminated` as terminal.
+- All state is local under `workspace_root`; nothing is sent anywhere.
+
+## Read commands with `--json`
+
+`status`, `status <id>`, `inspect <id>`, `logs <id>`, `overview`, `workflows`,
+`doctor`, `run`.

runspool-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-29
+
+Initial release.
+
+### Added
+- Local-first workflow engine backed by SQLite: tasks move through ordered
+  steps with a persisted state machine, event log, and per-step run history.
+- Full task lifecycle from the CLI: `init`, `add`, `run` (one-shot), `daemon`
+  (resident), `status`, `inspect`, `logs`, `overview`, `pause`, `resume`,
+  `retry`, `terminate`, `set-priority`, `set-retries`, `set-step`, `workflows`,
+  `doctor`.
+- `--json` output on every read command, plus an agent-friendly `inspect` that
+  returns `available_actions` and a `suggested_next_action`.
+- Automatic retries: a failed task is rescheduled (`retry_delay_seconds`) and
+  requeued by the coordinator until `max_retries` is reached, then becomes
+  `manual_required`.
+- Guarded state transitions enforced in the engine (not just the CLI): illegal
+  control actions on terminal/incompatible states are refused.
+- Graceful pause at step boundaries: a running step always finishes; pause
+  advances to the next step (or completes on the last) so no completed step is
+  re-run on resume.
+- Thread worker pool with per-step concurrency quotas, heartbeats, and stale-task
+  reclamation; startup recovery of interrupted tasks.
+- Dynamic step plugins loaded from config (`plugin_paths` + `import`), alongside
+  five dependency-free built-in steps.
+- Three runnable, offline examples: `local-file-pipeline`, `client-intel-brief`,
+  and `creator-publishing-pipeline` (draft-only).
+- Documentation (`docs/`), English + Simplified Chinese READMEs, and CI running
+  ruff, pytest (Python 3.11/3.12/3.13), and an example smoke test.
+
+[0.1.0]: https://github.com/ethan-sun-dev/runspool/releases/tag/v0.1.0

runspool-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+conduct@runspool.dev.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

runspool-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to Runspool
+
+Thanks for your interest in improving Runspool! This guide covers how to set up,
+make changes, and submit them.
+
+## Principles
+
+Runspool is intentionally small and focused. Before proposing a change, keep the
+project's character in mind:
+
+- **Local-first.** No hosted service, no required network access, no telemetry.
+- **CLI-first.** The command line and JSON output are the interface. No web UI.
+- **Predictable.** State transitions live in one state machine; keep them there.
+- **Small surface.** Prefer a plugin step over a new core dependency.
+
+See the [non-goals](README.md#non-goals) before suggesting large features.
+
+## Development setup
+
+```bash
+git clone https://github.com/ethan-sun-dev/runspool
+cd runspool
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Run the checks
+
+```bash
+ruff check .        # lint
+pytest              # tests
+```
+
+Both must pass before you open a pull request. To try the CLI end-to-end, run
+the [local-file-pipeline example](examples/local-file-pipeline/).
+
+## Making changes
+
+- **Match the surrounding style.** The codebase favors small, single-purpose
+  modules and clear comments explaining *why*, not *what*.
+- **Write tests.** New behavior needs a test; bug fixes need a regression test.
+  See [`tests/`](tests/) for patterns (fixtures live in `tests/conftest.py`).
+- **Keep the engine generic.** Engine, persistence, and CLI code must not depend
+  on any specific domain. Domain logic belongs in steps (built-in or plugin).
+- **Update docs.** If you change the CLI or the step contract, update the
+  relevant file under [`docs/`](docs/) and the README.
+- **English everywhere.** Code, comments, config, help text, and docs are in
+  English.
+
+## Adding a step
+
+Most new capabilities should be a step, not engine changes. See
+[docs/writing-steps.md](docs/writing-steps.md). If a step is broadly useful and
+dependency-free, it may belong in `src/runspool/builtin_steps/`; otherwise it's
+a great fit for an example or your own plugin.
+
+## Commit and PR
+
+- Keep commits focused with clear messages.
+- Fill in the pull request template (summary, related issue, checklist).
+- Link any relevant issue.
+
+## Reporting bugs and requesting features
+
+Use the issue templates. For bugs, include your OS, Python version, Runspool
+version, the commands you ran, and `runspool inspect <id> --json` output where
+relevant.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By
+participating, you agree to uphold it.

runspool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Runspool contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.