diff --git a/kits/agent-kiro-kit/README.md b/kits/agent-kiro-kit/README.md index 526df6ec..764289fc 100644 --- a/kits/agent-kiro-kit/README.md +++ b/kits/agent-kiro-kit/README.md @@ -33,6 +33,29 @@ async for event in adapter.stream("Summarize changes"): print(event) ``` +## Delivery stages + +A Delivery stage declares trust through the step's `config.sandbox` value: + +- `read-only` uses `--trust-tools=`. +- `workspace-write` uses `-a`. +- Headless mode ignores `sandbox` and uses the adapter's `trust_tools`; the + default is `--trust-all-tools`. + +The step's `timeout` is the stage time bound. When `beddel run` builds this +adapter with no constructor arguments, the adapter timeout is 600 seconds, so +the step timeout must be at most 600 seconds. A step timeout kills and reaps +the `kiro-cli` process. The subprocess inherits the repository cwd and +environment and receives closed stdin. Login comes from the existing +`kiro-cli` login or `KIRO_API_KEY` in the environment; credentials are never +passed as command-line arguments. + +The CLI does not report changed files, so `files_changed` is always `[]` and a +Delivery stage reads repository changes separately. Adapter errors use +`BEDDEL-AGENT-701` for execution failures and `BEDDEL-AGENT-702` for adapter +timeouts. A step timeout is raised as `BEDDEL-EXEC-005`; under the default FAIL +strategy the step failure `BEDDEL-EXEC-002` wraps it as its cause. + ## Headless Mode (CI/CD) For containers, CI/CD pipelines, and headless environments where browser-based SSO is unavailable, set the `KIRO_API_KEY` environment variable. The adapter automatically detects it and activates headless mode. @@ -125,7 +148,8 @@ If all steps fail, an `AgentError(BEDDEL-AGENT-701)` is raised. ## Running Tests +Run the kit tests from the kit directory with the Beddel SDK installed: + ```bash -cd repo/kits/agent-kiro-kit -PYTHONPATH="python:../../src/beddel-py/tests" python -m pytest tests/ -x +pytest -q ``` diff --git a/kits/agent-kiro-kit/python/beddel_agent_kiro/adapter.py b/kits/agent-kiro-kit/python/beddel_agent_kiro/adapter.py index a0842a87..604be07a 100644 --- a/kits/agent-kiro-kit/python/beddel_agent_kiro/adapter.py +++ b/kits/agent-kiro-kit/python/beddel_agent_kiro/adapter.py @@ -5,6 +5,13 @@ command. It implements the :class:`~beddel.domain.ports.IAgentAdapter` protocol via structural subtyping (no explicit inheritance). +Each execution inherits the caller's cwd and environment, closes stdin, +and is bounded by the constructor timeout. Interactive trust maps +``read-only`` to ``--trust-tools=`` and ``workspace-write`` to ``-a``; +headless trust uses ``trust_tools`` or defaults to ``--trust-all-tools``. +The CLI reports no changed-file list, so successful results always use +``files_changed=[]``. + The CLI is auto-discovered from ``~/.local/bin/kiro-cli`` or via ``shutil.which``. If neither resolves, the adapter attempts a one-time auto-install from ``https://cli.kiro.dev/install``. @@ -18,6 +25,7 @@ from __future__ import annotations import asyncio +import contextlib import os import shutil import subprocess @@ -38,13 +46,32 @@ _DEFAULT_CLI_PATH = Path.home() / ".local" / "bin" / "kiro-cli" +_REAP_GRACE_SECONDS = 2.0 + + +async def _terminate(proc: asyncio.subprocess.Process) -> None: + """Kill a subprocess during timeout or cancellation and bound the reap. + + ``Process.wait`` only returns after the output pipes close, so a child + of the CLI that inherited them would otherwise keep a timed-out stage + waiting. The direct child is reaped by the event loop either way. + """ + with contextlib.suppress(ProcessLookupError): + proc.kill() + with contextlib.suppress(TimeoutError): + async with asyncio.timeout(_REAP_GRACE_SECONDS): + await proc.wait() + + class KiroCLIAgentAdapter: """Kiro CLI agent adapter using subprocess execution. Implements the ``IAgentAdapter`` protocol structurally by exposing :meth:`execute` and :meth:`stream` with matching signatures. All interaction with the Kiro CLI happens through - ``asyncio.create_subprocess_exec``. + ``asyncio.create_subprocess_exec``. The subprocess inherits the + caller's cwd and environment, receives closed stdin, and is killed and + reaped on timeout or cancellation. Args: model: Default model identifier for CLI invocations. @@ -52,8 +79,9 @@ class KiroCLIAgentAdapter: auto-discovered from ``~/.local/bin/kiro-cli``, then ``shutil.which``, then auto-installed from the official installer script. - timeout: Maximum execution time in seconds before the subprocess - is killed. + timeout: Maximum execution time in seconds. The subprocess is + terminated and reaped when this bound expires or the caller + cancels the execution. api_key: Optional API key for headless mode. When provided (or when ``KIRO_API_KEY`` env var is set), the adapter operates in headless mode where sandbox is ignored and tool trust is @@ -171,7 +199,9 @@ async def execute( Returns: An :class:`AgentResult` with the CLI's stdout, exit code, - and execution metadata. + and execution metadata. ``files_changed`` is always empty + because the CLI does not report a file list; callers reconcile + repository changes separately. Raises: AgentError: ``BEDDEL-AGENT-702`` on timeout, or @@ -182,6 +212,7 @@ async def execute( proc = await asyncio.create_subprocess_exec( *cmd, + stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, ) @@ -192,13 +223,15 @@ async def execute( timeout=self._timeout, ) except TimeoutError as exc: - proc.kill() - await proc.wait() + await _terminate(proc) raise AgentError( code=AGENT_TIMEOUT, message=f"Kiro CLI process timed out after {self._timeout}s", details={"timeout": self._timeout, "cmd": [str(c) for c in cmd]}, ) from exc + except asyncio.CancelledError: + await _terminate(proc) + raise stdout_text = stdout_bytes.decode("utf-8", errors="replace") if stdout_bytes else "" stderr_text = stderr_bytes.decode("utf-8", errors="replace") if stderr_bytes else "" diff --git a/kits/agent-kiro-kit/tests/test_delivery_stage.py b/kits/agent-kiro-kit/tests/test_delivery_stage.py new file mode 100644 index 00000000..560bf77f --- /dev/null +++ b/kits/agent-kiro-kit/tests/test_delivery_stage.py @@ -0,0 +1,315 @@ +"""Real-subprocess tests for Delivery-stage Kiro adapter behavior.""" + +from __future__ import annotations + +import asyncio +import json +import os +import signal +import sys +import time +from pathlib import Path + +import beddel_agent_kiro.adapter as adapter_module +import pytest +from beddel.domain.errors import AgentError, BeddelError +from beddel.domain.executor import WorkflowExecutor +from beddel.domain.models import DefaultDependencies, Workflow +from beddel.domain.parser import WorkflowParser +from beddel.domain.registry import PrimitiveRegistry +from beddel.error_codes import ( + AGENT_EXECUTION_FAILED, + AGENT_TIMEOUT, + EXEC_STEP_FAILED, + EXEC_TIMEOUT, +) +from beddel.primitives import register_builtins +from beddel.tools.kits import discover_kits, load_kit_adapters +from beddel_agent_kiro.adapter import KiroCLIAgentAdapter + + +@pytest.fixture +def fake_cli(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> tuple[Path, Path]: + """Create an executable fake CLI that records its process context.""" + cli_path = tmp_path / "fake-kiro-cli" + log_path = tmp_path / "fake-kiro-log.json" + cli_path.write_text( + f"""#!{sys.executable} +import json +import os +import sys +import time + +record = {{ + "pid": os.getpid(), + "cwd": os.getcwd(), + "argv": sys.argv, + "mark": os.environ.get("FAKE_KIRO_MARK"), +}} +with open(os.environ["FAKE_KIRO_LOG"], "w") as log_file: + json.dump(record, log_file) + +mode = os.environ.get("FAKE_KIRO_MODE", "ok") +if mode == "ok": + sys.stdout.write("ok") +elif mode == "fail": + sys.exit(3) +elif mode == "sleep": + time.sleep(60) +elif mode == "grandchild": + import subprocess + + child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(8)"]) + with open(os.environ["FAKE_KIRO_CHILD_LOG"], "w") as child_log: + child_log.write(str(child.pid)) + time.sleep(60) +""" + ) + cli_path.chmod(0o755) + monkeypatch.setenv("FAKE_KIRO_LOG", str(log_path)) + monkeypatch.setenv("FAKE_KIRO_MODE", "ok") + monkeypatch.delenv("KIRO_API_KEY", raising=False) + return cli_path, log_path + + +def _read_record(log_path: Path) -> dict[str, object]: + """Read the fake CLI record after the process has started.""" + deadline = time.monotonic() + 5 + while time.monotonic() < deadline: + if log_path.exists(): + return json.loads(log_path.read_text()) + time.sleep(0.01) + raise AssertionError("fake CLI did not write its process record") + + +def _assert_pid_gone(pid: int) -> None: + """Assert that a recorded process exits within the stage cleanup bound.""" + deadline = time.monotonic() + 5 + while time.monotonic() < deadline: + try: + os.kill(pid, 0) + except ProcessLookupError: + return + time.sleep(0.01) + raise AssertionError(f"process {pid} is still running") + + +@pytest.mark.asyncio +async def test_success_returns_structured_result(fake_cli: tuple[Path, Path]) -> None: + cli_path, _log_path = fake_cli + adapter = KiroCLIAgentAdapter(cli_path=cli_path, model="model-default", timeout=17) + + result = await adapter.execute("prompt") + + assert result.exit_code == 0 + assert result.output == "ok" + assert result.events == [] + assert result.files_changed == [] + assert result.usage == {"model": "model-default", "timeout": 17} + assert result.agent_id == "kiro-cli" + + +@pytest.mark.asyncio +async def test_argv_uses_model_agent_and_read_only_trust( + fake_cli: tuple[Path, Path], +) -> None: + cli_path, log_path = fake_cli + adapter = KiroCLIAgentAdapter(cli_path=cli_path) + + await adapter.execute("prompt", model="m-x", sandbox="read-only", tools=["dev"]) + + record = _read_record(log_path) + assert record["argv"] == [ + str(cli_path), + "chat", + "--no-interactive", + "--trust-tools=", + "--model", + "m-x", + "--agent", + "dev", + "prompt", + ] + + +@pytest.mark.asyncio +async def test_workspace_write_uses_declared_trust(fake_cli: tuple[Path, Path]) -> None: + cli_path, log_path = fake_cli + adapter = KiroCLIAgentAdapter(cli_path=cli_path) + + await adapter.execute("prompt", sandbox="workspace-write") + + assert "-a" in _read_record(log_path)["argv"] + + +@pytest.mark.asyncio +async def test_headless_default_uses_trust_all_without_api_key_argv( + fake_cli: tuple[Path, Path], monkeypatch: pytest.MonkeyPatch +) -> None: + cli_path, log_path = fake_cli + dummy_key = "dummy-test-key" + monkeypatch.setenv("KIRO_API_KEY", dummy_key) + adapter = KiroCLIAgentAdapter(cli_path=cli_path) + + await adapter.execute("prompt", sandbox="read-only") + + argv = _read_record(log_path)["argv"] + assert "--trust-all-tools" in argv + assert dummy_key not in argv + + +@pytest.mark.asyncio +async def test_cwd_and_environment_are_inherited( + fake_cli: tuple[Path, Path], monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + cli_path, log_path = fake_cli + repo = tmp_path / "repo" + repo.mkdir() + monkeypatch.chdir(repo) + monkeypatch.setenv("FAKE_KIRO_MARK", "m") + adapter = KiroCLIAgentAdapter(cli_path=cli_path) + + await adapter.execute("prompt") + + record = _read_record(log_path) + assert record["cwd"] == str(repo) + assert record["mark"] == "m" + + +@pytest.mark.asyncio +async def test_non_zero_exit_raises_agent_error( + fake_cli: tuple[Path, Path], monkeypatch: pytest.MonkeyPatch +) -> None: + cli_path, _log_path = fake_cli + monkeypatch.setenv("FAKE_KIRO_MODE", "fail") + adapter = KiroCLIAgentAdapter(cli_path=cli_path) + + with pytest.raises(AgentError) as exc_info: + await adapter.execute("prompt") + + assert exc_info.value.code == AGENT_EXECUTION_FAILED + assert exc_info.value.details["exit_code"] == 3 + + +@pytest.mark.asyncio +async def test_adapter_timeout_kills_and_reaps_cli( + fake_cli: tuple[Path, Path], monkeypatch: pytest.MonkeyPatch +) -> None: + cli_path, log_path = fake_cli + monkeypatch.setenv("FAKE_KIRO_MODE", "sleep") + adapter = KiroCLIAgentAdapter(cli_path=cli_path, timeout=1) + + with pytest.raises(AgentError) as exc_info: + await adapter.execute("prompt") + + assert exc_info.value.code == AGENT_TIMEOUT + assert exc_info.value.details["timeout"] == 1 + _assert_pid_gone(int(_read_record(log_path)["pid"])) + + +def _delivery_executor( + cli_path: Path, monkeypatch: pytest.MonkeyPatch +) -> tuple[WorkflowExecutor, Workflow]: + """Build an executor and a one-step Delivery workflow with a no-arg adapter.""" + monkeypatch.setattr(adapter_module, "_DEFAULT_CLI_PATH", cli_path) + adapter = KiroCLIAgentAdapter() + workflow = WorkflowParser.parse( + """ + id: delivery-stage + name: Delivery stage + steps: + - id: deliver + primitive: agent-exec + config: + adapter: kiro-cli + prompt: implement the story + sandbox: workspace-write + timeout: 1 + """ + ) + registry = PrimitiveRegistry() + register_builtins(registry) + executor = WorkflowExecutor( + registry, + deps=DefaultDependencies(agent_registry={"kiro-cli": adapter}), + ) + return executor, workflow + + +@pytest.mark.asyncio +async def test_timeout_does_not_wait_for_a_child_holding_the_pipes( + fake_cli: tuple[Path, Path], monkeypatch: pytest.MonkeyPatch +) -> None: + cli_path, log_path = fake_cli + child_log = log_path.with_name("fake-kiro-child.pid") + monkeypatch.setenv("FAKE_KIRO_MODE", "grandchild") + monkeypatch.setenv("FAKE_KIRO_CHILD_LOG", str(child_log)) + adapter = KiroCLIAgentAdapter(cli_path=cli_path, timeout=1) + + started = time.monotonic() + try: + with pytest.raises(AgentError) as exc_info: + await adapter.execute("prompt") + elapsed = time.monotonic() - started + finally: + # Release the pipes held by the grandchild so the loop can close them. + if child_log.exists(): + os.kill(int(child_log.read_text()), signal.SIGKILL) + await asyncio.sleep(0.3) + + assert exc_info.value.code == AGENT_TIMEOUT + assert elapsed < 6, "the reap must be bounded, the grandchild lives 8 s" + _assert_pid_gone(int(_read_record(log_path)["pid"])) + + +@pytest.mark.asyncio +async def test_agent_exec_step_result_has_the_three_adapter_keys( + fake_cli: tuple[Path, Path], monkeypatch: pytest.MonkeyPatch +) -> None: + cli_path, _log_path = fake_cli + executor, workflow = _delivery_executor(cli_path, monkeypatch) + + result = await executor.execute(workflow, {}) + + step_result = result["step_results"]["deliver"] + assert set(step_result) == {"output", "files_changed", "usage"} + assert step_result["output"] == "ok" + assert step_result["files_changed"] == [] + + +@pytest.mark.asyncio +async def test_step_timeout_kills_cli_before_executor_returns( + fake_cli: tuple[Path, Path], monkeypatch: pytest.MonkeyPatch +) -> None: + cli_path, log_path = fake_cli + monkeypatch.setenv("FAKE_KIRO_MODE", "sleep") + executor, workflow = _delivery_executor(cli_path, monkeypatch) + + with pytest.raises(BeddelError) as exc_info: + await executor.execute(workflow, {}) + + # The executor's default FAIL strategy wraps the step timeout in a step failure. + assert exc_info.value.code == EXEC_STEP_FAILED + cause = exc_info.value.__cause__ + assert isinstance(cause, BeddelError) + assert cause.code == EXEC_TIMEOUT + _assert_pid_gone(int(_read_record(log_path)["pid"])) + + +def test_no_arg_build_loads_manifest_adapter( + monkeypatch: pytest.MonkeyPatch, +) -> None: + kit_root = Path(__file__).resolve().parent.parent + monkeypatch.delenv("KIRO_API_KEY", raising=False) + monkeypatch.setattr(adapter_module, "_DEFAULT_CLI_PATH", Path(sys.executable)) + + discovery = discover_kits([kit_root.parent]) + manifest = next( + item for item in discovery.manifests if item.kit.name == "agent-kiro-kit" + ) + adapters = load_kit_adapters(manifest) + + adapter = adapters[("IAgentAdapter", "kiro-cli")] + assert isinstance(adapter, KiroCLIAgentAdapter) + assert adapter._timeout == 600 + assert adapter._trust_tools is None diff --git a/kits/agent-kiro-kit/tests/test_kiro_cli.py b/kits/agent-kiro-kit/tests/test_kiro_cli.py index a83ed999..55c50493 100644 --- a/kits/agent-kiro-kit/tests/test_kiro_cli.py +++ b/kits/agent-kiro-kit/tests/test_kiro_cli.py @@ -2,6 +2,7 @@ from __future__ import annotations +import asyncio from pathlib import Path from typing import Any from unittest.mock import AsyncMock, MagicMock, patch @@ -287,7 +288,7 @@ async def test_happy_path(self) -> None: @pytest.mark.asyncio async def test_subprocess_receives_no_cwd(self) -> None: - """Characterize today's inherited cwd; Story 7.2a is expected to change it.""" + """The subprocess inherits the repository cwd and environment.""" adapter = KiroCLIAgentAdapter() mock_proc = _make_mock_process() @@ -295,6 +296,8 @@ async def test_subprocess_receives_no_cwd(self) -> None: await adapter.execute(_PROMPT) assert "cwd" not in mock_exec.call_args.kwargs + assert "env" not in mock_exec.call_args.kwargs + assert mock_exec.call_args.kwargs["stdin"] is asyncio.subprocess.DEVNULL @pytest.mark.asyncio async def test_non_zero_exit_code(self) -> None: @@ -334,6 +337,30 @@ async def test_timeout(self) -> None: mock_proc.kill.assert_called_once() mock_proc.wait.assert_awaited_once() + @pytest.mark.asyncio + async def test_cancellation_kills_the_process(self) -> None: + adapter = KiroCLIAgentAdapter() + mock_proc = _make_mock_process() + blocked = asyncio.Event() + started = asyncio.Event() + + async def _wait_forever() -> tuple[bytes, bytes]: + started.set() + await blocked.wait() + return b"", b"" + + mock_proc.communicate.side_effect = _wait_forever + + with patch(_PATCH_EXEC, return_value=mock_proc): + task = asyncio.create_task(adapter.execute(_PROMPT)) + await started.wait() + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + + mock_proc.kill.assert_called_once() + mock_proc.wait.assert_awaited_once() + # =================================================================== # stream() (AC 6)