agent-workflow-sdk 0.6.0__tar.gz → 0.6.2__tar.gz

{agent_workflow_sdk-0.6.0 → agent_workflow_sdk-0.6.2}/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `agent-workflow-sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project aims to follow [Semantic Versioning](https://semver.org/).
 
+## [0.6.2] - 2026-11-05
+
+### Fixed
+
+- On Windows the `kiro-cli` child now runs in a kill-on-close Job Object. A hard
+  kill ends the whole tree (`kiro-cli-chat` included), and if the host Python
+  process dies the OS ends it too. `taskkill /F /T` stays as the fallback. A
+  grandchild spawned in the first instant before the child joins the job is only
+  covered by that fallback.
+
+## [0.6.1] - 2026-11-05
+
+### Fixed
+
+- `KiroBackend.close()` no longer raises `AttributeError` on Windows, where
+  `signal.SIGKILL`, `os.killpg` and `os.getpgid` do not exist. Shutdown escalates
+  by intent (terminate, then kill): POSIX still signals the process group; on
+  Windows the hard kill runs `taskkill /F /T` so grandchildren such as
+  `kiro-cli-chat` are reaped, then `proc.kill()`.
+
 ## [0.6.0] - 2026-09-29
 
 ### Changed (breaking)

{agent_workflow_sdk-0.6.0 → agent_workflow_sdk-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-workflow-sdk
-Version: 0.6.0
+Version: 0.6.2
 Summary: Async-first SDK for orchestrating local coding-agent CLIs (Claude Code, Codex, Kiro) and LLMs as durable, graph-based workflows.
 Project-URL: Homepage, https://github.com/dankosorkin/agent-workflow-sdk
 Project-URL: Repository, https://github.com/dankosorkin/agent-workflow-sdk

{agent_workflow_sdk-0.6.0 → agent_workflow_sdk-0.6.2}/agentflow/__init__.py

@@ -99,7 +99,7 @@ from agentflow.state import (
 from agentflow.store import Item, MemoryStore, Store
 from agentflow.telemetry import JsonlTelemetry, MultiHooks
 
-__version__ = "0.6.0"
+__version__ = "0.6.2"
 
 __all__ = [
     "__version__",

agent_workflow_sdk-0.6.2/agentflow/backends/_winjob.py

@@ -0,0 +1,152 @@
+# Copyright 2026 Daniel Sorkin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Windows Job Objects: keep a child and everything it spawns on a leash.
+
+Windows has no process groups. A Job Object created with
+``JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`` contains a process and its descendants:
+terminating the job kills the whole tree, and when the last handle to the job
+closes (including because *our* process crashed or was killed) the OS kills the
+tree itself, so no ``kiro-cli-chat`` is left behind.
+
+Standard library (``ctypes``) only. Every function is a safe no-op returning
+``None``/``False`` off Windows or when the API call fails, so callers can fall
+back to ``taskkill``. A process is assigned after it starts, so a grandchild
+spawned in that first instant is not covered; the ``taskkill /T`` fallback exists
+for that.
+
+Known limit: a process already inside a job that forbids nesting cannot be
+assigned (Windows 8+ allows nested jobs, so this is rare).
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+_KILL_ON_JOB_CLOSE = 0x2000
+_JOB_OBJECT_EXTENDED_LIMIT_INFORMATION = 9
+_PROCESS_TERMINATE = 0x0001
+_PROCESS_SET_QUOTA = 0x0100
+
+
+def _kernel32() -> Any:
+    """kernel32 with 64-bit-safe signatures, or ``None`` when not on Windows."""
+    if sys.platform != "win32":
+        return None
+    import ctypes
+    from ctypes import wintypes
+
+    k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    k32.CreateJobObjectW.argtypes = [wintypes.LPVOID, wintypes.LPCWSTR]
+    k32.CreateJobObjectW.restype = wintypes.HANDLE
+    k32.SetInformationJobObject.argtypes = [
+        wintypes.HANDLE,
+        ctypes.c_int,
+        wintypes.LPVOID,
+        wintypes.DWORD,
+    ]
+    k32.SetInformationJobObject.restype = wintypes.BOOL
+    k32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    k32.OpenProcess.restype = wintypes.HANDLE
+    k32.AssignProcessToJobObject.argtypes = [wintypes.HANDLE, wintypes.HANDLE]
+    k32.AssignProcessToJobObject.restype = wintypes.BOOL
+    k32.TerminateJobObject.argtypes = [wintypes.HANDLE, wintypes.UINT]
+    k32.TerminateJobObject.restype = wintypes.BOOL
+    k32.CloseHandle.argtypes = [wintypes.HANDLE]
+    k32.CloseHandle.restype = wintypes.BOOL
+    return k32
+
+
+def _limit_info() -> Any:
+    """A JOBOBJECT_EXTENDED_LIMIT_INFORMATION with KILL_ON_JOB_CLOSE set."""
+    import ctypes
+    from ctypes import wintypes
+
+    class BasicLimits(ctypes.Structure):
+        _fields_ = [
+            ("PerProcessUserTimeLimit", ctypes.c_int64),
+            ("PerJobUserTimeLimit", ctypes.c_int64),
+            ("LimitFlags", wintypes.DWORD),
+            ("MinimumWorkingSetSize", ctypes.c_size_t),
+            ("MaximumWorkingSetSize", ctypes.c_size_t),
+            ("ActiveProcessLimit", wintypes.DWORD),
+            ("Affinity", ctypes.c_size_t),
+            ("PriorityClass", wintypes.DWORD),
+            ("SchedulingClass", wintypes.DWORD),
+        ]
+
+    class IoCounters(ctypes.Structure):
+        _fields_ = [(n, ctypes.c_uint64) for n in ("r_ops", "w_ops", "o_ops", "r_b", "w_b", "o_b")]
+
+    class ExtendedLimits(ctypes.Structure):
+        _fields_ = [
+            ("BasicLimitInformation", BasicLimits),
+            ("IoInfo", IoCounters),
+            ("ProcessMemoryLimit", ctypes.c_size_t),
+            ("JobMemoryLimit", ctypes.c_size_t),
+            ("PeakProcessMemoryUsed", ctypes.c_size_t),
+            ("PeakJobMemoryUsed", ctypes.c_size_t),
+        ]
+
+    info = ExtendedLimits()
+    info.BasicLimitInformation.LimitFlags = _KILL_ON_JOB_CLOSE
+    return info
+
+
+def attach(pid: int) -> Any | None:
+    """Put process ``pid`` in a new kill-on-close job and return the job handle.
+
+    Returns ``None`` (nothing to clean up) off Windows or if any step fails.
+    """
+    import ctypes
+
+    k32 = _kernel32()
+    if k32 is None:
+        return None
+    job = k32.CreateJobObjectW(None, None)
+    if not job:
+        return None
+    info = _limit_info()
+    ok = k32.SetInformationJobObject(
+        job, _JOB_OBJECT_EXTENDED_LIMIT_INFORMATION, ctypes.byref(info), ctypes.sizeof(info)
+    )
+    if not ok:
+        k32.CloseHandle(job)
+        return None
+    process = k32.OpenProcess(_PROCESS_SET_QUOTA | _PROCESS_TERMINATE, False, pid)
+    if not process:
+        k32.CloseHandle(job)
+        return None
+    try:
+        assigned = k32.AssignProcessToJobObject(job, process)
+    finally:
+        k32.CloseHandle(process)
+    if not assigned:
+        k32.CloseHandle(job)
+        return None
+    return job
+
+
+def terminate(job: Any) -> bool:
+    """Kill every process in ``job``. ``True`` if Windows accepted it."""
+    k32 = _kernel32()
+    return bool(k32 is not None and job and k32.TerminateJobObject(job, 1))
+
+
+def close(job: Any) -> None:
+    """Release the job handle; with kill-on-close this also kills any survivor."""
+    k32 = _kernel32()
+    if k32 is not None and job:
+        k32.CloseHandle(job)

{agent_workflow_sdk-0.6.0 → agent_workflow_sdk-0.6.2}/agentflow/backends/kiro.py

@@ -32,10 +32,13 @@ import contextlib
 import json
 import os
 import signal
+import subprocess
+import sys
 from collections.abc import AsyncIterator
 from pathlib import Path
 from typing import Any, Literal
 
+from agentflow.backends import _winjob
 from agentflow.backends.base import BaseAgentBackend, PermissionPolicy
 from agentflow.errors import BackendError, BackendTransportError
 from agentflow.events import (
@@ -83,6 +86,8 @@ class KiroBackend(BaseAgentBackend):
         self._close_grace = close_grace
 
         self._proc: asyncio.subprocess.Process | None = None
+        # Windows only: the kill-on-close Job Object holding the child's whole tree.
+        self._job: Any = None
         self._session_id: str | None = None
         self._request_id = 0
 
@@ -131,6 +136,8 @@ class KiroBackend(BaseAgentBackend):
             )
         except OSError as exc:
             raise BackendTransportError(f"could not start kiro-cli: {exc}") from exc
+        if sys.platform == "win32":
+            self._job = _winjob.attach(self._proc.pid)
 
         self._reader_task = asyncio.create_task(self._read_loop())
 
@@ -156,35 +163,51 @@ class KiroBackend(BaseAgentBackend):
             try:
                 await asyncio.wait_for(proc.wait(), timeout=self._close_grace)
             except TimeoutError:
-                self._signal_group(proc, signal.SIGTERM)
+                self._stop(proc, hard=False, job=self._job)
                 try:
                     await asyncio.wait_for(proc.wait(), timeout=self._close_grace)
                 except TimeoutError:
-                    self._signal_group(proc, signal.SIGKILL)
+                    self._stop(proc, hard=True, job=self._job)
         finally:
             if self._reader_task:
                 self._reader_task.cancel()
                 with contextlib.suppress(asyncio.CancelledError, Exception):
                     await self._reader_task
             self._proc = None
+            if self._job is not None:
+                # Kill-on-close: also reaps any descendant that outlived a clean exit.
+                _winjob.close(self._job)
+                self._job = None
             self._fail_pending(BackendTransportError("backend closed"))
 
     @staticmethod
-    def _signal_group(proc: asyncio.subprocess.Process, sig: int) -> None:
-        """Send ``sig`` to the child's whole process group, if possible.
-
-        The child was started with ``start_new_session=True`` so it leads its
-        own group; signalling ``-pgid`` reaches its descendants too. Falls back
-        to signalling just the process where process groups aren't available
-        (e.g. Windows) or the group has already gone. Never raises.
+    def _stop(proc: asyncio.subprocess.Process, *, hard: bool, job: Any = None) -> None:
+        """Stop ``proc`` by intent (soft: terminate, hard: kill). Never raises.
+
+        POSIX: SIGTERM/SIGKILL to the child's process group (it leads its own
+        via ``start_new_session=True``), reaching its descendants. Windows has
+        no ``signal.SIGKILL``/``os.killpg``/``os.getpgid``, so nothing
+        platform-specific is read unguarded: the hard kill terminates the Job Object
+        holding the whole tree (``taskkill /F /T`` if there is none), then ``proc.kill()``.
         """
-        with contextlib.suppress(ProcessLookupError, PermissionError, OSError, AttributeError):
-            pgid = os.getpgid(proc.pid)
-            os.killpg(pgid, sig)
-            return
-        # Fallback: signal the process directly.
+        killpg = getattr(os, "killpg", None)
+        getpgid = getattr(os, "getpgid", None)
+        sig = getattr(signal, "SIGKILL" if hard else "SIGTERM", None)
+        if killpg is not None and getpgid is not None and sig is not None:
+            with contextlib.suppress(ProcessLookupError, PermissionError, OSError, AttributeError):
+                killpg(getpgid(proc.pid), sig)
+                return
+        if hard and sys.platform == "win32" and not (job is not None and _winjob.terminate(job)):
+            with contextlib.suppress(OSError, subprocess.SubprocessError):
+                subprocess.run(
+                    ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    timeout=5,
+                    check=False,
+                )
         with contextlib.suppress(ProcessLookupError, OSError):
-            if sig == signal.SIGKILL:
+            if hard:
                 proc.kill()
             else:
                 proc.terminate()

{agent_workflow_sdk-0.6.0 → agent_workflow_sdk-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-workflow-sdk"
-version = "0.6.0"
+version = "0.6.2"
 description = "Async-first SDK for orchestrating local coding-agent CLIs (Claude Code, Codex, Kiro) and LLMs as durable, graph-based workflows."
 readme = "README.md"
 requires-python = ">=3.11"

{agent_workflow_sdk-0.6.0 → agent_workflow_sdk-0.6.2}/tests/test_kiro_backend.py

@@ -24,6 +24,10 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
+import signal
+import subprocess
+import sys
 
 import pytest
 from agentflow.backends.base import AllowAll, DenyAll
@@ -303,6 +307,119 @@ async def test_close_terminates_then_kills_on_timeout(fake_proc, monkeypatch):
     assert fake_proc.returncode == -9  # kill() was reached
 
 
+async def test_close_on_windows_has_no_posix_signals(fake_proc, monkeypatch):
+    """Windows shape: no signal.SIGKILL / os.killpg / os.getpgid. close() must not
+    raise AttributeError and must reap the tree with taskkill, then kill."""
+    backend = KiroBackend("fake-agent", engine="v2", permission=AllowAll())
+    setup = asyncio.create_task(_drive_setup(fake_proc))
+    await backend.start()
+    await setup
+    fake_proc.pid = 4242
+
+    async def _never() -> int:
+        await asyncio.sleep(3600)
+        return 0
+
+    async def _fast_wait_for(coro, timeout):
+        coro.close()
+        raise TimeoutError
+
+    monkeypatch.setattr(fake_proc, "wait", _never)
+    monkeypatch.setattr(asyncio, "wait_for", _fast_wait_for)
+    monkeypatch.delattr(os, "killpg", raising=False)
+    monkeypatch.delattr(os, "getpgid", raising=False)
+    monkeypatch.delattr(signal, "SIGKILL", raising=False)
+    monkeypatch.setattr(sys, "platform", "win32")
+    ran: list[list[str]] = []
+    monkeypatch.setattr(subprocess, "run", lambda cmd, **kw: ran.append(cmd))
+
+    await backend.close()
+
+    assert ran == [["taskkill", "/F", "/T", "/PID", "4242"]]
+    assert fake_proc.returncode == -9
+
+
+async def _windows_close_with_job(fake_proc, monkeypatch, *, job_terminates: bool):
+    """close() on 'Windows' that must escalate, with a Job Object already attached."""
+    from agentflow.backends import _winjob
+
+    backend = KiroBackend("fake-agent", engine="v2", permission=AllowAll())
+    setup = asyncio.create_task(_drive_setup(fake_proc))
+    await backend.start()
+    await setup
+    fake_proc.pid = 4242
+    backend._job = "JOB"
+
+    async def _never() -> int:
+        await asyncio.sleep(3600)
+        return 0
+
+    async def _fast_wait_for(coro, timeout):
+        coro.close()
+        raise TimeoutError
+
+    monkeypatch.setattr(fake_proc, "wait", _never)
+    monkeypatch.setattr(asyncio, "wait_for", _fast_wait_for)
+    monkeypatch.delattr(os, "killpg", raising=False)
+    monkeypatch.delattr(os, "getpgid", raising=False)
+    monkeypatch.setattr(sys, "platform", "win32")
+    events: list[str] = []
+    monkeypatch.setattr(
+        _winjob, "terminate", lambda job: events.append("job-terminate") or job_terminates
+    )
+    monkeypatch.setattr(_winjob, "close", lambda job: events.append("job-close"))
+    monkeypatch.setattr(subprocess, "run", lambda cmd, **kw: events.append("taskkill"))
+
+    await backend.close()
+    return events, backend
+
+
+async def test_windows_start_puts_the_child_in_a_job(fake_proc, monkeypatch):
+    from agentflow.backends import _winjob
+
+    fake_proc.pid = 777
+    attached: list[int] = []
+    monkeypatch.setattr(sys, "platform", "win32")
+    monkeypatch.setattr(_winjob, "attach", lambda pid: attached.append(pid) or "JOB")
+    backend = KiroBackend("fake-agent", engine="v2", permission=AllowAll())
+    setup = asyncio.create_task(_drive_setup(fake_proc))
+    await backend.start()
+    await setup
+
+    assert attached == [777]
+    assert backend._job == "JOB"
+
+
+async def test_windows_hard_kill_terminates_the_job_not_taskkill(fake_proc, monkeypatch):
+    events, backend = await _windows_close_with_job(fake_proc, monkeypatch, job_terminates=True)
+
+    assert events == ["job-terminate", "job-close"]
+    assert backend._job is None
+
+
+async def test_windows_hard_kill_falls_back_to_taskkill_when_the_job_fails(fake_proc, monkeypatch):
+    events, _ = await _windows_close_with_job(fake_proc, monkeypatch, job_terminates=False)
+
+    assert events == ["job-terminate", "taskkill", "job-close"]
+
+
+async def test_windows_clean_exit_still_releases_the_job(fake_proc, monkeypatch):
+    from agentflow.backends import _winjob
+
+    backend = KiroBackend("fake-agent", engine="v2", permission=AllowAll())
+    setup = asyncio.create_task(_drive_setup(fake_proc))
+    await backend.start()
+    await setup
+    backend._job = "JOB"
+    closed: list[str] = []
+    monkeypatch.setattr(_winjob, "close", lambda job: closed.append(job))
+
+    await backend.close()  # the fake process exits at once: no escalation
+
+    assert closed == ["JOB"]
+    assert backend._job is None
+
+
 async def test_turn_rpc_failure_yields_error_event(fake_proc):
     backend = KiroBackend("fake-agent", engine="v2", permission=AllowAll())
     setup = asyncio.create_task(_drive_setup(fake_proc))

agent_workflow_sdk-0.6.2/tests/test_winjob.py

@@ -0,0 +1,83 @@
+"""Job Object wrapper, against a fake kernel32 (the real one exists only on Windows)."""
+
+from __future__ import annotations
+
+import sys
+
+from agentflow.backends import _winjob
+
+
+class _K32:
+    def __init__(self, *, fail: str | None = None) -> None:
+        self.fail = fail
+        self.calls: list[str] = []
+
+    def CreateJobObjectW(self, *a):  # noqa: N802
+        self.calls.append("create")
+        return None if self.fail == "create" else 11
+
+    def SetInformationJobObject(self, job, cls, info, size):  # noqa: N802
+        self.calls.append(f"set:{cls}:{info._obj.BasicLimitInformation.LimitFlags:#x}")
+        return 0 if self.fail == "set" else 1
+
+    def OpenProcess(self, access, inherit, pid):  # noqa: N802
+        self.calls.append(f"open:{access:#x}:{pid}")
+        return None if self.fail == "open" else 22
+
+    def AssignProcessToJobObject(self, job, process):  # noqa: N802
+        self.calls.append(f"assign:{job}:{process}")
+        return 0 if self.fail == "assign" else 1
+
+    def TerminateJobObject(self, job, code):  # noqa: N802
+        self.calls.append(f"terminate:{job}")
+        return 1
+
+    def CloseHandle(self, handle):  # noqa: N802
+        self.calls.append(f"close:{handle}")
+        return 1
+
+
+def test_everything_is_a_noop_off_windows(monkeypatch):
+    monkeypatch.setattr(sys, "platform", "linux")
+    assert _winjob.attach(1) is None
+    assert _winjob.terminate(object()) is False
+    _winjob.close(object())  # must not raise
+
+
+def test_attach_builds_a_kill_on_close_job_and_assigns_the_process(monkeypatch):
+    k32 = _K32()
+    monkeypatch.setattr(_winjob, "_kernel32", lambda: k32)
+
+    job = _winjob.attach(4242)
+
+    assert job == 11
+    assert k32.calls == [
+        "create",
+        "set:9:0x2000",  # extended limits, KILL_ON_JOB_CLOSE
+        "open:0x101:4242",  # SET_QUOTA | TERMINATE
+        "assign:11:22",
+        "close:22",  # the process handle is released, the job handle is kept
+    ]
+
+
+def test_attach_cleans_up_after_each_failure(monkeypatch):
+    for step, expected_tail in [
+        ("create", []),
+        ("set", ["close:11"]),
+        ("open", ["close:11"]),
+        ("assign", ["close:22", "close:11"]),
+    ]:
+        k32 = _K32(fail=step)
+        monkeypatch.setattr(_winjob, "_kernel32", lambda k=k32: k)
+        assert _winjob.attach(1) is None, step
+        assert k32.calls[len(k32.calls) - len(expected_tail) :] == expected_tail, step
+
+
+def test_terminate_and_close_use_the_job_handle(monkeypatch):
+    k32 = _K32()
+    monkeypatch.setattr(_winjob, "_kernel32", lambda: k32)
+
+    assert _winjob.terminate(11) is True
+    _winjob.close(11)
+
+    assert k32.calls == ["terminate:11", "close:11"]