superwait 0.3.1__tar.gz → 0.3.2__tar.gz

{superwait-0.3.1 → superwait-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: superwait
-Version: 0.3.1
+Version: 0.3.2
 Summary: Conditional waiting for coding agents
 Project-URL: Repository, https://github.com/ctxrs/superwait
 Project-URL: Issues, https://github.com/ctxrs/superwait/issues

{superwait-0.3.1 → superwait-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "superwait"
-version = "0.3.1"
+version = "0.3.2"
 description = "Conditional waiting for coding agents"
 readme = "README.md"
 license = "MIT"

{superwait-0.3.1 → superwait-0.3.2}/src/superwait/SKILL.md

@@ -8,7 +8,7 @@ description: Prefer superwait for waiting on agents, files, services, or signals
 Prefer superwait for observable conditions. Use native tools to spawn or steer
 agents, or when superwait reports unobserved workers. Don't retry missing hooks.
 
-Call the `wait_for` MCP tool:
+Prefer a direct `wait_for` MCP call (avoids code-mode wrapper wakeups):
 
 ```json
 {"request":{"agents":["worker-a-id","worker-b-id"],"timeout":"10m"}}
@@ -17,14 +17,15 @@ Call the `wait_for` MCP tool:
 Use handles returned by the host. For Codex `/root/...` paths, add `session`
 from startup context. The default waits for all agents. Read the `ready`
 reports; use `continue_wait` as the next `request` for remaining work.
+For a resumed worker, use an agent target with `after` set to its last cursor.
 Choose the real task deadline, not repeated 30–60-second timeouts. An expired
-continuation stays expired. Native process handles still need their native tools.
+continuation stays expired. On an agent timeout, check native status before
+extending: recorded state can be stale. Native process handles need native tools.
 
-In Codex code mode, start `functions.exec` with
+If only Codex code mode is available, start `functions.exec` with
 `// @exec: {"yield_time_ms":60000}`. If it yields, resume that cell with
-`functions.wait` and `yield_time_ms: 60000`.
-The wrapper can still wake the model; prefer a direct tool call when available.
+`functions.wait` and `yield_time_ms: 60000`. Print `result.structuredContent`
+once, not the entire MCP envelope.
 
-For other conditions, quorum, early wakeups, continuation details, or CLI usage,
-read the [local API reference](references/api.md) only when needed, including
-the CLI fallback if the MCP tool is not exposed.
+For target syntax, direct-tool configuration, quorum, early wakeups, or the CLI
+fallback, read the [local API reference](references/api.md) when needed.

{superwait-0.3.1 → superwait-0.3.2}/src/superwait/engine.py

@@ -182,7 +182,7 @@ async def wait_for(request: WaitRequest, store: Store, progress=None):
             if e := r.get("event"):
                 c["cursor"] = e["seq"]
                 if isinstance(t, Agent):
-                    c.update(id=e["key"], handle=t.id, session=e["session"])
+                    c.update(id=e["key"], handle=t.id, session=e["session"], last_observed_at=e["at"])
                 if r["matched"]:
                     data = e["data"]
                     field = "report" if data.get("report") else "summary"
@@ -212,6 +212,12 @@ async def wait_for(request: WaitRequest, store: Store, progress=None):
             ready = [card(t, r) for t, r, _ in main if r["matched"]]
             pending = [card(t, r) for t, r, _ in main if not r["matched"]]
             triggered = [card(t, r) for t, r, _ in wake if r["matched"]]
+            if status == "timed_out":
+                for c in pending:
+                    if c["kind"] == "agent" and "cursor" in c:
+                        c["hint"] = ("This is the last recorded lifecycle observation, not live worker status. "
+                                     "A stop or interruption may have gone unrecorded. Check the worker with "
+                                     "the host's native tools before extending the deadline.")
             reason = {
                 "matched": f"{len(ready)} of {len(primary)} targets ready; {needed} required.",
                 "interrupted": "Wake condition matched: " + ", ".join(str(c["label"]) for c in triggered),

{superwait-0.3.1 → superwait-0.3.2}/src/superwait/references/api.md

@@ -110,6 +110,13 @@ Codex task paths can remain pending while a worker in the specified parent is
 running, because their aliases are learned at stop. Already observed workers
 can run for the full requested deadline.
 
+Hook observations are not a live worker-status feed. In Codex, interruption or
+a missing stop hook can leave a worker recorded as `running`; follow-up turns
+can leave the previous `stopped` observation in place until the next stop.
+On an agent timeout, inspect the worker with native tools before extending the
+deadline. Superwait does not infer completion or failure from elapsed time.
+Use `after` for follow-up responses, as shown below.
+
 ### Other MCP tools
 
 `list_agents(provider, session?)` returns `agents` and `limit` (50) for recent
@@ -144,7 +151,9 @@ The result includes:
 - `continue_wait`: a ready-to-use request for remaining work, or `null`
 
 Reports include the observed state, available worker result, and event cursor
-where applicable. `details: true` adds `checks` and raw `targets` / `wake_on`
+where applicable. Agent cards with an observation include `last_observed_at`
+(Unix seconds); a timed-out pending agent also includes a native-status check
+hint. `details: true` adds `checks` and raw `targets` / `wake_on`
 observations. An early wake condition wins if it and the main threshold match
 in the same check.
 
@@ -180,14 +189,33 @@ deadline survives continuation; a timed-out continuation remains expired.
 Choose the actual task deadline rather than repeatedly issuing short waits.
 Use `wake_on` for blockers that should interrupt it.
 
-In Codex code mode, start `functions.exec` with
+Prefer a direct MCP call when exposed. In Codex code mode, start `functions.exec` with
 `// @exec: {"yield_time_ms":60000}`. If it yields, resume that cell with
 `functions.wait` and `yield_time_ms: 60000`. This avoids unnecessary model
 turns collecting an unfinished tool call.
 The wrapper still requires model interactions when it yields; superwait cannot
-remove the host's execution-cell limit. Prefer a direct MCP call when exposed.
+remove the host's execution-cell limit. When printing a nested MCP result, print
+`result.structuredContent` once; the full envelope repeats it as text too.
 Native terminal/process handles still require the native collection tool.
 
+### Direct tools in Codex code mode
+
+Codex 0.153.1 supports exposing selected namespaces directly. If code mode is
+enabled, add `mcp__superwait` to this list in your Codex configuration:
+
+```toml
+[features.code_mode]
+direct_only_tool_namespaces = ["mcp__superwait"]
+```
+
+Edit an existing table/list in place and preserve any other namespaces; do not
+add a duplicate TOML table. Start a fresh session and verify `wait_for` is a
+direct tool. This removes execution-cell resume calls for that wait, not MCP
+timeouts or turns needed for other work. Setup does not change this optional,
+Codex-specific setting.
+
+### CLI fallback
+
 For long Cursor waits, or waits beyond a host's configured MCP timeout, run the
 same request through the host's background terminal:
 

{superwait-0.3.1 → superwait-0.3.2}/tests/test_observations.py

@@ -84,6 +84,39 @@ async def test_other_parent_cannot_keep_unknown_path_wait_alive(tmp_path, monkey
     assert result["status"] == "error"
 
 
+@pytest.mark.parametrize("state,after", [("running", 0), ("stopped", 1)])
+async def test_agent_timeout_exposes_observation_age_and_native_fallback(tmp_path, state, after):
+    store = Store(tmp_path / "db")
+    cursor = store.emit("agent", "worker", state, provider="codex", session="parent")
+    observed_at = store.latest("agent", "worker", provider="codex")["at"]
+    result = await wait_for(WaitRequest(targets=[{"kind": "agent", "provider": "codex",
+        "id": "worker", "after": after}], timeout="100ms", interval=.05), store)
+    assert result["status"] == "timed_out"
+    pending = result["pending"][0]
+    assert pending["state"] == ("running" if state == "running" else "awaiting_new_event")
+    assert pending["cursor"] == cursor
+    assert pending["last_observed_at"] == observed_at
+    assert "native tools" in pending["hint"]
+    # A timeout must neither manufacture a terminal event nor lose its deadline.
+    assert store.latest("agent", "worker", provider="codex")["seq"] == cursor
+    assert result["continue_wait"]["deadline"] == result["deadline"]
+
+
+async def test_matched_agent_and_file_timeout_do_not_get_stale_worker_hint(tmp_path):
+    store = Store(tmp_path / "db")
+    store.emit("agent", "worker", "stopped", provider="codex", session="parent", data={"summary": "done"})
+    result = await wait_for(WaitRequest(agents=["worker"], timeout="1s"), store)
+    assert result["status"] == "matched"
+    assert result["ready"][0]["result"] == "done"
+    assert "last_observed_at" in result["ready"][0]
+    assert "hint" not in result["ready"][0]
+    result = await wait_for(WaitRequest(targets=[{"kind": "file", "path": str(tmp_path / "absent")}],
+                                        timeout="100ms"), store)
+    assert result["status"] == "timed_out"
+    assert "hint" not in result["pending"][0]
+    assert "last_observed_at" not in result["pending"][0]
+
+
 async def test_unknown_agent_does_not_override_ready_quorum_or_wake(tmp_path):
     store = Store(tmp_path / "db")
     store.emit("signal", "ready", "ready")

{superwait-0.3.1 → superwait-0.3.2}/uv.lock

@@ -746,7 +746,7 @@ wheels = [
 
 [[package]]
 name = "superwait"
-version = "0.3.1"
+version = "0.3.2"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },