superwait 0.2.0__tar.gz

superwait-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+dist/
+*.egg-info/
+.superwait/

superwait-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+Use Python 3.11+ and uv. From a checkout:
+
+```sh
+uv sync --locked
+uv run --locked pytest
+uv build
+```
+
+The tests use temporary databases, synthetic lifecycle events, local HTTP
+endpoints, subprocesses, and a real stdio MCP client. Keep them independent of
+personal agent accounts, configuration, and conversation history.
+
+For integration changes, include a focused regression and state which host
+versions were actually exercised. Keep timeout, cancellation, and partial-result
+behavior explicit. Adapter tests alone do not establish live host compatibility.
+
+Submit changes through pull requests. Describe the observable behavior and how
+you checked it. Avoid adding a service or framework when the existing wait
+engine, host feature, or standard library is sufficient.

superwait-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Superwait 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.

superwait-0.2.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: superwait
+Version: 0.2.0
+Summary: Conditional waiting for coding agents
+Project-URL: Repository, https://github.com/ctxrs/superwait
+Project-URL: Issues, https://github.com/ctxrs/superwait/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx2<3,>=2.13
+Requires-Dist: mcp<3,>=2.2
+Requires-Dist: pydantic<3,>=2.12
+Description-Content-Type: text/markdown
+
+# Superwait
+
+Conditional waiting for coding agents. Wait for any, all, or a count of workers
+and other conditions, wake early on a blocker, and keep one deadline across
+interruptions.
+
+Superwait provides an MCP tool and CLI, with setup for Codex, Claude Code, and
+Cursor. The agent chooses the workflow; local code checks the conditions.
+There are no model calls inside the wait.
+
+## Install
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv tool install superwait
+superwait setup codex --project /path/to/project
+# Other hosts:
+superwait setup claude --project /path/to/project
+superwait setup cursor --project /path/to/project
+```
+
+Setup installs project-local MCP settings, lifecycle hooks, and agent
+instructions. It preserves unrelated settings and backs up changed files as
+`.superwait-backup`. Restart the host and accept its normal trust prompts.
+Install hooks before spawning workers, and keep the Python tool environment
+installed. See [host integration](https://github.com/ctxrs/superwait/blob/main/docs/hosts.md) for details.
+
+To install the current source instead, use
+`uv tool install 'git+https://github.com/ctxrs/superwait'`.
+
+Linux is tested. Codex has live integration coverage; Claude Code and Cursor
+have adapter tests and still need full live workflow qualification. Other
+operating systems and multi-hour host waits remain unqualified.
+
+## Express the wait
+
+Call the MCP tool `wait_for` with a `request`. For example, wait for two of three
+reviewers, or return early when an explicit blocker signal arrives:
+
+```json
+{
+  "request": {
+    "agents": ["reviewer-a-id", "reviewer-b-id", "reviewer-c-id"],
+    "mode": "quorum",
+    "quorum": 2,
+    "wake_on": [{"kind": "signal", "key": "review-42/blocker", "state": "blocked"}],
+    "timeout": "2h"
+  }
+}
+```
+
+Use the native worker IDs from your host. The provider defaults to the host
+selected during setup. Codex task paths such as `/root/reviewer_a` also work
+when accompanied by the parent `session` supplied in its startup context.
+`list_agents` is available for discovery and troubleshooting.
+
+`mode` is `all` by default, or `any`, or `quorum` with a count. Add `targets` for
+other conditions; they count toward the same threshold as `agents`.
+
+| Condition | Matches when |
+| --- | --- |
+| `agent` | A lifecycle hook observes a requested worker state |
+| `signal` | A task-specific event is published |
+| `file` | A path exists, is missing, changes, or contains literal text |
+| `http` | A GET returns the requested status code |
+| `command` | An observational command returns the requested exit code |
+
+Checks run concurrently. Command probes take an argument array and run without
+a shell; use an observational check because it repeats. `interval` controls
+polling, with a default of one second. Use absolute paths when the MCP server's
+working directory may differ from yours.
+
+Publish an explicit checkpoint or blocker through the `signal` MCP tool or CLI:
+
+```sh
+superwait signal review-42/blocker --state blocked --data '{"reason":"missing fixture"}'
+```
+
+## Act on the result
+
+The result includes `status`, `reason`, completed reports in `ready`, remaining
+work in `pending`, and early wake conditions in `triggered`.
+
+Pass the returned `continue_wait` object back as the next request to continue.
+It preserves the deadline, remaining count, and file-change baselines, and
+advances past delivered event signals. Persistent conditions such as an existing
+blocker file must clear or be removed before continuing. After a quorum has
+already been reached, continuation waits for all remaining work.
+
+A stopped response does not prove an assignment succeeded. Read its report;
+another host hook may continue that worker. For a resumed worker, use an `agent`
+target with `after` set to its last returned `cursor`. Unknown workers stay
+pending. `details: true` adds raw observations for troubleshooting.
+
+## Long waits and the CLI
+
+Setup configures a per-server MCP timeout of 24 hours plus 30 seconds for Codex
+and Claude Code. `setup --max-wait 3d` changes that ceiling. Each request still
+has its own timeout or timezone-qualified `deadline`. An absolute deadline
+survives continuation; a timed-out continuation remains expired.
+
+For long Cursor waits, or waits beyond the host's configured MCP timeout, run
+the same engine through the host's background terminal:
+
+```sh
+superwait wait --request wait.json --output result.json
+```
+
+`wait.json` contains the request itself, without the MCP `request` wrapper.
+The CLI prints one final JSON result and atomically saves the optional output.
+It exits 0 for matched/early wake, 124 for timeout, 130 for Ctrl-C, and 2 for an
+invalid request or target ambiguity. Native completion notifications or terminal
+collection retrieve the result; the CLI does not background itself.
+
+Cancellation stops the wait and any probes it launched. It never cancels the
+workers being observed. The machine and process must remain alive.
+
+## Local state
+
+Hooks and waiters share a local SQLite database, defaulting to
+`$XDG_STATE_HOME/superwait/events.sqlite3` or
+`~/.local/state/superwait/events.sqlite3`. Set `SUPERWAIT_DB` or `--db` to use
+another store. Stored observations include worker IDs, report excerpts, and
+available transcript paths. `superwait prune --days 30` removes old observations.
+
+The Codex task-name adapter reads only the metadata header of the exact worker
+transcript supplied by its hook. It does not scan conversation history.
+Network requests occur only for requested HTTP or command checks.
+
+See [contributing](https://github.com/ctxrs/superwait/blob/main/CONTRIBUTING.md)
+for local development. Licensed under [MIT](https://github.com/ctxrs/superwait/blob/main/LICENSE).

superwait-0.2.0/README.md

@@ -0,0 +1,132 @@
+# Superwait
+
+Conditional waiting for coding agents. Wait for any, all, or a count of workers
+and other conditions, wake early on a blocker, and keep one deadline across
+interruptions.
+
+Superwait provides an MCP tool and CLI, with setup for Codex, Claude Code, and
+Cursor. The agent chooses the workflow; local code checks the conditions.
+There are no model calls inside the wait.
+
+## Install
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv tool install superwait
+superwait setup codex --project /path/to/project
+# Other hosts:
+superwait setup claude --project /path/to/project
+superwait setup cursor --project /path/to/project
+```
+
+Setup installs project-local MCP settings, lifecycle hooks, and agent
+instructions. It preserves unrelated settings and backs up changed files as
+`.superwait-backup`. Restart the host and accept its normal trust prompts.
+Install hooks before spawning workers, and keep the Python tool environment
+installed. See [host integration](https://github.com/ctxrs/superwait/blob/main/docs/hosts.md) for details.
+
+To install the current source instead, use
+`uv tool install 'git+https://github.com/ctxrs/superwait'`.
+
+Linux is tested. Codex has live integration coverage; Claude Code and Cursor
+have adapter tests and still need full live workflow qualification. Other
+operating systems and multi-hour host waits remain unqualified.
+
+## Express the wait
+
+Call the MCP tool `wait_for` with a `request`. For example, wait for two of three
+reviewers, or return early when an explicit blocker signal arrives:
+
+```json
+{
+  "request": {
+    "agents": ["reviewer-a-id", "reviewer-b-id", "reviewer-c-id"],
+    "mode": "quorum",
+    "quorum": 2,
+    "wake_on": [{"kind": "signal", "key": "review-42/blocker", "state": "blocked"}],
+    "timeout": "2h"
+  }
+}
+```
+
+Use the native worker IDs from your host. The provider defaults to the host
+selected during setup. Codex task paths such as `/root/reviewer_a` also work
+when accompanied by the parent `session` supplied in its startup context.
+`list_agents` is available for discovery and troubleshooting.
+
+`mode` is `all` by default, or `any`, or `quorum` with a count. Add `targets` for
+other conditions; they count toward the same threshold as `agents`.
+
+| Condition | Matches when |
+| --- | --- |
+| `agent` | A lifecycle hook observes a requested worker state |
+| `signal` | A task-specific event is published |
+| `file` | A path exists, is missing, changes, or contains literal text |
+| `http` | A GET returns the requested status code |
+| `command` | An observational command returns the requested exit code |
+
+Checks run concurrently. Command probes take an argument array and run without
+a shell; use an observational check because it repeats. `interval` controls
+polling, with a default of one second. Use absolute paths when the MCP server's
+working directory may differ from yours.
+
+Publish an explicit checkpoint or blocker through the `signal` MCP tool or CLI:
+
+```sh
+superwait signal review-42/blocker --state blocked --data '{"reason":"missing fixture"}'
+```
+
+## Act on the result
+
+The result includes `status`, `reason`, completed reports in `ready`, remaining
+work in `pending`, and early wake conditions in `triggered`.
+
+Pass the returned `continue_wait` object back as the next request to continue.
+It preserves the deadline, remaining count, and file-change baselines, and
+advances past delivered event signals. Persistent conditions such as an existing
+blocker file must clear or be removed before continuing. After a quorum has
+already been reached, continuation waits for all remaining work.
+
+A stopped response does not prove an assignment succeeded. Read its report;
+another host hook may continue that worker. For a resumed worker, use an `agent`
+target with `after` set to its last returned `cursor`. Unknown workers stay
+pending. `details: true` adds raw observations for troubleshooting.
+
+## Long waits and the CLI
+
+Setup configures a per-server MCP timeout of 24 hours plus 30 seconds for Codex
+and Claude Code. `setup --max-wait 3d` changes that ceiling. Each request still
+has its own timeout or timezone-qualified `deadline`. An absolute deadline
+survives continuation; a timed-out continuation remains expired.
+
+For long Cursor waits, or waits beyond the host's configured MCP timeout, run
+the same engine through the host's background terminal:
+
+```sh
+superwait wait --request wait.json --output result.json
+```
+
+`wait.json` contains the request itself, without the MCP `request` wrapper.
+The CLI prints one final JSON result and atomically saves the optional output.
+It exits 0 for matched/early wake, 124 for timeout, 130 for Ctrl-C, and 2 for an
+invalid request or target ambiguity. Native completion notifications or terminal
+collection retrieve the result; the CLI does not background itself.
+
+Cancellation stops the wait and any probes it launched. It never cancels the
+workers being observed. The machine and process must remain alive.
+
+## Local state
+
+Hooks and waiters share a local SQLite database, defaulting to
+`$XDG_STATE_HOME/superwait/events.sqlite3` or
+`~/.local/state/superwait/events.sqlite3`. Set `SUPERWAIT_DB` or `--db` to use
+another store. Stored observations include worker IDs, report excerpts, and
+available transcript paths. `superwait prune --days 30` removes old observations.
+
+The Codex task-name adapter reads only the metadata header of the exact worker
+transcript supplied by its hook. It does not scan conversation history.
+Network requests occur only for requested HTTP or command checks.
+
+See [contributing](https://github.com/ctxrs/superwait/blob/main/CONTRIBUTING.md)
+for local development. Licensed under [MIT](https://github.com/ctxrs/superwait/blob/main/LICENSE).

superwait-0.2.0/docs/hosts.md

@@ -0,0 +1,104 @@
+# Host integration
+
+All three hosts use the same `wait_for`, `list_agents`, and `signal` MCP API.
+The CLI runs the same wait engine. Setup writes only to the project you name.
+
+| Host | MCP configuration | Lifecycle hook configuration | Skill |
+| --- | --- | --- | --- |
+| Codex | `.codex/config.toml` | `.codex/hooks.json` | `.agents/skills/superwait/SKILL.md` |
+| Claude Code | `.mcp.json` | `.claude/settings.json` | `.claude/skills/superwait/SKILL.md` |
+| Cursor | `.cursor/mcp.json` | `.cursor/hooks.json` | `.cursor/skills/superwait/SKILL.md` |
+
+## Codex
+
+`SubagentStart` and `SubagentStop` supply the agent ID and parent session ID.
+Superwait records the last assistant message when present. A stop hook observes
+a response ending before other stop hooks necessarily finish deciding whether
+to continue it. It is not a durable promise that the agent will never run again.
+
+Some Codex runtimes return a task path such as `/root/reviewer` from spawning,
+but lifecycle hooks report a UUID. Both can now be passed directly to `agents`.
+At the stop hook, Superwait reads only the first metadata record of the
+exact worker transcript Codex supplies. It validates both worker and parent IDs
+before recording the task path. This metadata adapter supports the Codex 0.153.1
+header format. It reads no conversation body and scans
+no history. It is version-dependent; absent or unsupported metadata leaves
+UUID-based waiting and explicit signals available.
+
+A previously unknown task path remains pending until that mapping arrives.
+Task paths require `session` even if only one old mapping exists: an unscoped
+name could otherwise match a previous conversation before the new worker stops.
+Setup installs a SessionStart hook that supplies this context to Codex; it
+makes no permission decisions. The CLI fills missing scope from CODEX_THREAD_ID
+only for task paths. Explicit session values and ordinary UUIDs are preserved.
+Duplicate or ambiguous references return an actionable error. `list_agents`
+remains available for discovery and diagnosis, with UUIDs in `key` and observed
+task paths in `data.aliases`.
+
+Setup sets `tool_timeout_sec` to the desired maximum wait plus 30 seconds.
+The server sends MCP progress keepalives during normal polling; these do not
+override the client's hard timeout. The tool remains cancellable.
+
+For noninteractive `codex exec`, first review and trust the hooks with `/hooks`
+in the same project and Codex home. A `never` approval policy cannot approve
+MCP calls that still require a prompt. After reviewing this server's access,
+configure `tools.wait_for.approval_mode = "approve"` and the other needed tools
+under `[mcp_servers.superwait]`, or use that server's
+`default_tools_approval_mode = "approve"`. Setup leaves that decision to the
+host's normal approval flow. This approval includes repeated command and HTTP
+probes with the server process's access.
+
+Sources: [hooks](https://developers.openai.com/codex/hooks),
+[MCP settings](https://learn.chatgpt.com/docs/extend/mcp),
+[skill discovery](https://learn.chatgpt.com/docs/build-skills).
+
+## Claude Code
+
+The same lifecycle event names provide `agent_id` and `session_id`. Setup also
+observes `PostToolUse` for `SubagentHandback` because newer versions can deliver
+the actual report there; the final assistant text may only be a closing note.
+The report does not itself mark the agent as stopped.
+
+The per-server `timeout` is in milliseconds. Current Claude Code can background
+long MCP calls and notify on completion; its wall-clock limit still applies.
+The CLI can also run under Bash or Monitor. Monitor receives its final JSON line
+when the wait returns. A killed subagent may never emit a stop event, so retain
+the wait's deadline and check native status if needed.
+
+Sources: [hook payloads](https://code.claude.com/docs/en/hooks#subagentstop),
+[MCP timeouts/backgrounding](https://code.claude.com/docs/en/mcp),
+[Monitor](https://code.claude.com/docs/en/tools-reference#monitor-tool).
+
+## Cursor
+
+`subagentStart` includes `subagent_id` and `parent_conversation_id`.
+The documented `subagentStop` payload can omit both. Superwait uses the common
+conversation ID and matches the exact task/type fingerprint only when there is
+one running candidate in that parent. Concurrent identical tasks remain
+unmatched. No timing heuristic guesses which agent finished.
+
+For these cases, assign unique outcome signal keys in worker instructions.
+Signals also work for checkpoints and blockers in every host. Cursor's explicit
+`error` and `aborted` stop states are preserved when correlated.
+
+The public MCP documentation does not specify a supported long-call timeout
+setting. Setup does not invent one. Prefer the CLI through the background
+terminal for hours-long waits. A live Cursor build is needed to qualify its
+background completion delivery and exact hook payloads.
+
+Sources: [hooks](https://cursor.com/docs/hooks),
+[MCP](https://cursor.com/docs/mcp),
+[subagents](https://cursor.com/docs/subagents).
+
+## Permissions and lifecycle
+
+The tool does not bypass host permissions. MCP/terminal/hook trust is still
+owned by the host. A predicate is an operation: HTTP requests and command probes
+use the access of the local server process, so authorize it as you would other
+local MCP tools. Use observational probes because they run repeatedly.
+
+Signals are local observations, not messages to other tasks. No hosted service,
+cloud account, or model endpoint is involved. Hooks and CLI use one shared
+SQLite store. No provider database is accessed. The Codex task-name adapter
+reads the metadata header described above; Claude and Cursor use their
+documented hook fields.

superwait-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "superwait"
+version = "0.2.0"
+description = "Conditional waiting for coding agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = ["mcp>=2.2,<3", "httpx2>=2.13,<3", "pydantic>=2.12,<3"]
+
+[project.urls]
+Repository = "https://github.com/ctxrs/superwait"
+Issues = "https://github.com/ctxrs/superwait/issues"
+
+[project.scripts]
+superwait = "superwait.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=1"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/superwait"]

superwait-0.2.0/src/superwait/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: superwait
+description: Wait for agents and external conditions together, with any/all/quorum, early wake conditions, long deadlines, and useful partial results.
+---
+
+# Superwait
+
+Express when you want to wake. You choose the workflow; native tools remain
+available for spawning, steering, or collecting additional results.
+
+## One request
+
+Call wait_for with a request. For example, wait for two reviewers, wake early
+on a blocker, and stop after two hours:
+
+~~~json
+{
+  "agents": ["/root/reviewer_a", "/root/reviewer_b", "/root/reviewer_c"],
+  "session": "parent-session-from-startup-context",
+  "mode": "quorum",
+  "quorum": 2,
+  "wake_on": [{"kind": "signal", "key": "review-42/blocker", "state": "blocked", "label": "Review blocked"}],
+  "timeout": "2h"
+}
+~~~
+
+agents accepts native IDs and Codex task paths directly. The installed host
+is the default provider; set provider for a different host. Hooks must be
+installed before spawning. Codex paths become resolvable when its stop hook
+supplies the worker metadata. Codex task paths require the parent session from
+the SessionStart context supplied by setup; this prevents matching an old
+conversation with the same names. The Codex CLI fallback fills it from the
+calling thread's environment. Native UUIDs need no extra scope.
+list_agents is available for discovery or troubleshooting, not a prerequisite.
+
+mode is all by default, or any, or quorum with a count. Add targets
+for other conditions; they and agents count toward the same threshold.
+wake_on returns early independently of that threshold. Add label to any
+condition to make its meaning explicit in the result.
+
+~~~json
+{"kind":"file","path":"/workspace/ci-failed.json","label":"CI failed"}
+{"kind":"http","url":"http://localhost:8080/health","status":200}
+{"kind":"signal","key":"build-42","state":"ready"}
+{"kind":"file","path":"/workspace/server.log","event":"contains","text":"Ready"}
+{"kind":"command","argv":["python3","/workspace/check_ci.py"],"exit_code":0}
+~~~
+
+Files support exists (default), missing, changed, and literal contains.
+HTTP matches the status code. Command probes run repeatedly without a shell;
+use an observational check, not the build/deploy itself. Prefer absolute paths.
+interval controls polling, default 1 second; increase it for remote services.
+
+## Use the result
+
+- status: matched, interrupted, timed_out, or error.
+- reason and triggered: why the wait ended and which early condition fired.
+- ready: observed results and event cursors; pending: remaining work/errors.
+- continue_wait: a ready-to-use request for the remaining work, or null.
+
+After handling an interruption, pass continue_wait back as the next request
+if you want to continue. It retains the absolute deadline and file-change
+baselines, carries the remaining quorum, and consumes delivered event signals.
+Persistent conditions such as an existing blocker file must clear or be removed
+from wake_on before proceeding. After reaching a quorum, continuation waits
+for all remaining work. It does not repeat reports you already received.
+
+timeout accepts 30s, 10m, 2h, or 1d. A timezone-qualified deadline
+overrides it. A timed-out continuation remains expired; choose a new deadline
+explicitly if you want more time. For a resumed worker, use an agent target
+with after set to its last returned cursor to await a new response:
+
+~~~json
+{"session":"parent-session","targets":[{"kind":"agent","provider":"codex","id":"/root/reviewer_a","after":42}],"timeout":"2h"}
+~~~
+
+A stopped response is not proof the assignment passed; read its result. Another
+stop hook can continue a worker. Unknown workers stay pending. Cursor stop
+hooks sometimes lack enough identity: use an explicit unique outcome signal
+for indistinguishable concurrent assignments. Signal keys should identify the
+particular task; existing matching signals count unless after excludes them.
+Use signal(key, state, data) for explicit checkpoints and outcomes.
+
+## Long waits and cancellation
+
+Setup configures Codex/Claude's MCP timeout for 24 hours by default. For waits
+beyond the configured host limit, or long Cursor waits, use the same request
+with superwait wait --request wait.json --output result.json in the host's
+background terminal. The CLI emits one final result; normal host notifications
+or native collection retrieve it. It does not wake a closed conversation.
+
+Cancel the MCP call or send Ctrl-C to the CLI to stop waiting. The observed
+workers continue; only the wait's own probes are cleaned up. The process and
+machine must stay alive. CLI exits: 0 matched/interrupted, 124 timeout,
+130 cancelled, 2 error. details: true adds raw observations for diagnosis.

superwait-0.2.0/src/superwait/__init__.py

@@ -0,0 +1 @@
+"""Conditional waits with no model calls between observations."""

superwait-0.2.0/src/superwait/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()