Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -27,21 +27,35 @@ jobs:
components: rustfmt
- run: cargo fmt --check

# The SDKs and the VS Code extension, against their fake incode/agent.
# The SDKs and the VS Code extension, against their fake incode/agent. The
# SDKs on the oldest runtimes they promise (Node 18, Python 3.9) as well as
# current ones; the extension on the Node VS Code ships. Python 3.9 is past
# its end of life and setup-python has no build of it for the Ubuntu
# `ubuntu-latest` now is (26.04: "The version '3.9' ... was not found"), so
# that leg runs on 22.04.
sdk-and-editor:
runs-on: ubuntu-latest
name: sdk-and-editor (node ${{ matrix.node }}, python ${{ matrix.python }})
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
include:
- { node: 18, python: "3.9", os: ubuntu-22.04 }
- { node: 20, python: "3.12", os: ubuntu-latest }
- { node: 22, python: "3.12", os: ubuntu-latest }
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
node-version: ${{ matrix.node }}
- uses: actions/setup-python@v5
with:
python-version: "3.12"
python-version: ${{ matrix.python }}
- run: python3 -m unittest discover sdk/python/tests
- run: npm ci && npm test
working-directory: sdk/typescript
- run: npm ci && npm run compile && npm test
if: matrix.node == 22
working-directory: editors/vscode

test:
Expand Down
6 changes: 5 additions & 1 deletion sdk/python/incode_sdk/__init__.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
"""Drive the incode coding agent from Python.

* :func:`run_task` — one instruction, ``incode -t ... --output-format json``.
* :func:`stream_task` — the same, ``stream-json``: each event as it arrives.
* :class:`Session` — an interactive session over ACP, ``incode --acp``.
* :mod:`incode_sdk.aio` — awaitable wrappers of both.
"""
Expand Down Expand Up @@ -30,11 +31,14 @@
)
from .fs import FsAccessDenied, FsError, WorkspaceFS # noqa: E402
from .session import PromptStream, Session, allow_all, reject_all # noqa: E402
from .task import TaskResult, TaskUsage, run_task # noqa: E402
from .task import TaskEvent, TaskResult, TaskStream, TaskUsage, run_task, stream_task # noqa: E402

__all__ = [
"__version__",
"run_task",
"stream_task",
"TaskEvent",
"TaskStream",
"TaskResult",
"TaskUsage",
"Session",
Expand Down
167 changes: 162 additions & 5 deletions sdk/python/incode_sdk/task.py
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
"""One-shot runs: ``incode -t "<task>" --output-format json``."""
"""One-shot runs: ``incode -t "<task>" --output-format json`` (:func:`run_task`)
or ``stream-json``, one event at a time (:func:`stream_task`)."""

import json
import os
import subprocess
import threading
from dataclasses import dataclass, field
from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
from typing import Any, Dict, Iterator, List, Mapping, Optional, Sequence, Union

from .errors import IncodeError, IncodeTimeout, ProtocolError, TaskFailed

__all__ = ["TaskResult", "TaskUsage", "run_task", "build_task_argv"]
__all__ = ["TaskEvent", "TaskResult", "TaskStream", "TaskUsage", "run_task", "stream_task", "build_task_argv"]

PathLike = Union[str, "os.PathLike[str]"]

Expand Down Expand Up @@ -91,10 +93,12 @@ def build_task_argv(
permission_mode: Optional[str] = None,
incode_path: Union[PathLike, Sequence[str]] = "incode",
extra_args: Sequence[str] = (),
output_format: str = "json",
) -> List[str]:
"""The command line :func:`run_task` runs."""
"""The command line :func:`run_task` (``json``) or :func:`stream_task`
(``stream-json``) runs."""
argv = _command(incode_path)
argv += ["-t", task, "--output-format", "json"]
argv += ["-t", task, "--output-format", output_format]
if workspace is not None:
argv += ["-w", os.fspath(workspace)]
if model:
Expand Down Expand Up @@ -198,6 +202,159 @@ def run_task(
return result


@dataclass
class TaskEvent:
"""One line of ``incode -t ... --output-format stream-json`` before the
result: ``type`` is ``init``, ``text``, ``thinking``, ``notice``,
``tool_use``, ``tool_result`` or ``usage`` (src/task_run.rs
``Report::event``); ``data`` is the whole object."""

type: str
data: Dict[str, Any]


class TaskStream:
"""A ``stream-json`` run: iterate it for :class:`TaskEvent`\\ s as they
arrive. When iteration ends, :attr:`result` holds the run's
:class:`TaskResult`; a failed run raises at the end of iteration, as
:func:`run_task` would (:class:`TaskFailed`, :class:`IncodeTimeout`,
:class:`IncodeError`, :class:`ProtocolError`). :meth:`wait` drains what is
left and returns the result."""

def __init__(self, argv: List[str], timeout: Optional[float], env: Optional[Mapping[str, str]]):
self.result: Optional[TaskResult] = None
self._timeout = timeout
self._timed_out = False
self._stderr: List[str] = []
try:
self._proc = subprocess.Popen(
argv,
stdin=subprocess.DEVNULL,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
env=env,
)
except FileNotFoundError as e:
raise IncodeError("could not start incode: %s (looked for %r)" % (e.strerror, argv[0])) from e
except PermissionError as e:
raise IncodeError("could not start incode: %s (%r)" % (e.strerror, argv[0])) from e
# stderr is read on its own thread, so a full pipe never stalls the run.
self._stderr_thread = threading.Thread(target=self._read_stderr, daemon=True)
self._stderr_thread.start()
self._timer: Optional[threading.Timer] = None
if timeout is not None:
self._timer = threading.Timer(timeout, self._kill_for_time)
self._timer.daemon = True
self._timer.start()
self._events = self._run()

def _read_stderr(self) -> None:
assert self._proc.stderr is not None
for chunk in iter(lambda: self._proc.stderr.read(4096), b""): # type: ignore[union-attr]
self._stderr.append(_text(chunk))

def _kill_for_time(self) -> None:
self._timed_out = True
self._proc.kill()

@property
def stderr(self) -> str:
"""What incode wrote on stderr so far."""
return "".join(self._stderr)

def __iter__(self) -> Iterator[TaskEvent]:
return self._events

def wait(self) -> TaskResult:
"""Read the rest of the run and return its result (raising as
iteration would)."""
for _ in self._events:
pass
assert self.result is not None
return self.result

def _run(self) -> Iterator[TaskEvent]:
assert self._proc.stdout is not None
data: Optional[Dict[str, Any]] = None
try:
for raw in self._proc.stdout:
line = _text(raw).strip()
if not line:
continue
try:
value = json.loads(line)
except ValueError:
self._proc.kill()
self._finish()
raise ProtocolError(
"incode -t printed a line that is not JSON: %r" % line[:500], stderr=self.stderr
) from None
if not isinstance(value, dict):
continue
if value.get("type") == "result":
data = value
continue
yield TaskEvent(type=str(value.get("type") or ""), data=value)
finally:
code = self._finish()
if self._timed_out:
raise IncodeTimeout("incode -t did not finish within %ss" % self._timeout, stderr=self.stderr)
if data is None:
if code != 0:
raise IncodeError("incode -t failed before producing a result", stderr=self.stderr, exit_code=code)
raise ProtocolError("incode -t printed no JSON result object", stderr=self.stderr, exit_code=code)
self.result = TaskResult.from_json(data, exit_code=code, stderr=self.stderr)
if self.result.is_error or code != 0:
raise TaskFailed(
"incode -t reported an error: %s" % (self.result.error or "unknown error"),
result=self.result,
stderr=self.stderr,
exit_code=code,
)

def _finish(self) -> int:
code = self._proc.wait()
if self._timer is not None:
self._timer.cancel()
self._stderr_thread.join(timeout=5)
# Both pipes are done with once the process has exited and stderr is
# read: closed, so a program streaming many runs does not leak them.
for pipe in (self._proc.stdout, self._proc.stderr):
if pipe is not None:
pipe.close()
return code


def stream_task(
task: str,
*,
workspace: Optional[PathLike] = None,
model: Optional[str] = None,
permission_mode: Optional[str] = None,
timeout: Optional[float] = None,
incode_path: Union[PathLike, Sequence[str]] = "incode",
env: Optional[Mapping[str, str]] = None,
extra_args: Sequence[str] = (),
) -> TaskStream:
"""Run one instruction with ``incode -t ... --output-format stream-json``:
a :class:`TaskStream` yielding each event as it arrives, then holding the
result. Takes the arguments :func:`run_task` takes."""
argv = build_task_argv(
task,
workspace=workspace,
model=model,
permission_mode=permission_mode,
incode_path=incode_path,
extra_args=extra_args,
output_format="stream-json",
)
full_env = None
if env is not None:
full_env = dict(os.environ)
full_env.update(env)
return TaskStream(argv, timeout, full_env)


def _text(data: Any) -> str:
if data is None:
return ""
Expand Down
56 changes: 55 additions & 1 deletion sdk/python/tests/test_task.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

from _support import FAKE

from incode_sdk import IncodeError, IncodeTimeout, ProtocolError, TaskFailed, TaskResult, run_task
from incode_sdk import IncodeError, IncodeTimeout, ProtocolError, TaskFailed, TaskResult, run_task, stream_task
from incode_sdk.aio import run_task_async
from incode_sdk.task import build_task_argv

Expand Down Expand Up @@ -114,5 +114,59 @@ def test_async(self):
self.assertEqual(result.result, "done: hello")


class StreamTaskTest(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.ws = self.tmp.name

def tearDown(self):
self.tmp.cleanup()

def test_events_arrive_in_order_then_the_result(self):
argv_file = os.path.join(self.ws, "argv.json")
stream = stream_task("add a test", workspace=self.ws, incode_path=FAKE, env={"FAKE_INCODE_ARGV": argv_file})
events = list(stream)
self.assertEqual([e.type for e in events], ["init", "text", "tool_use", "tool_result", "usage"])
self.assertEqual(events[1].data["text"], "working on: add a test")
self.assertEqual(events[2].data["name"], "Read")
self.assertIsNotNone(stream.result)
self.assertEqual(stream.result.result, "done: add a test")
self.assertEqual(stream.result.usage.input_tokens, 120)
with open(argv_file, encoding="utf-8") as f:
argv = json.load(f)
self.assertIn("stream-json", argv)
self.assertNotIn("result", [e.type for e in events], "the result is not an event")

def test_wait_returns_the_result(self):
self.assertEqual(stream_task("hello", workspace=self.ws, incode_path=FAKE).wait().result, "done: hello")

def test_a_failed_run_raises_at_the_end_with_its_events_seen(self):
seen = []
with self.assertRaises(TaskFailed) as cm:
for event in stream_task("fail now", workspace=self.ws, incode_path=FAKE):
seen.append(event.type)
self.assertEqual(seen[0], "init")
self.assertTrue(cm.exception.result.is_error)

def test_a_line_that_is_not_json_is_a_protocol_error(self):
with self.assertRaises(ProtocolError):
list(stream_task("events-garbage", workspace=self.ws, incode_path=FAKE))

def test_a_crash_is_an_incode_error_with_stderr(self):
with self.assertRaises(IncodeError) as cm:
list(stream_task("crash", workspace=self.ws, incode_path=FAKE))
self.assertIn("could not start", cm.exception.stderr)

def test_a_timeout_kills_the_run(self):
with self.assertRaises(IncodeTimeout):
list(stream_task("sleep", workspace=self.ws, incode_path=FAKE, timeout=1))

def test_argv(self):
self.assertEqual(
build_task_argv("hi", output_format="stream-json"),
["incode", "-t", "hi", "--output-format", "stream-json"],
)


if __name__ == "__main__":
unittest.main()
19 changes: 19 additions & 0 deletions sdk/testing/fake_incode.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@
``sleep`` -> sleeps 30 s (for timeouts)
otherwise -> success, ``result`` is ``"done: <task>"``

With ``--output-format stream-json``, the events ``init``, ``text``,
``tool_use``, ``tool_result`` and ``usage`` come first, one per line
(``events-garbage`` adds a line that is not JSON after them).

* ``fake_incode.py --acp`` speaks ACP (newline-delimited JSON-RPC 2.0) on
stdin/stdout, mirroring ``src/acp_agent``: ``initialize``, ``session/new``,
``session/load``, ``session/prompt``, ``session/cancel``, ``session/set_mode``,
Expand Down Expand Up @@ -108,6 +112,21 @@ def run_task(args):
result["error"] = "nothing to do: the instruction is empty" if not task.strip() else "the agent failed: fake failure"
else:
result["result"] = "done: " + task
if fmt == "stream-json":
# The events src/task_run.rs `Report::init` / `Report::event` write
# before the result, one JSON object per line.
for event in (
{"type": "init", "session_id": result["session_id"], "agent": "claude-code", "model": result["model"]},
{"type": "text", "text": "working on: " + task},
{"type": "tool_use", "id": "t1", "name": "Read", "input": {"path": "README.md"}},
{"type": "tool_result", "id": "t1", "output": "read it", "is_error": False},
{"type": "usage", "input_tokens": 120, "output_tokens": 45, "cache_creation_tokens": 7, "cache_read_tokens": 300},
):
sys.stdout.write(json.dumps(event) + "\n")
sys.stdout.flush()
if word == "events-garbage":
sys.stdout.write("this is not json\n")
sys.stdout.flush()
if fmt in ("json", "stream-json"):
sys.stdout.write(json.dumps(result) + "\n")
else:
Expand Down
4 changes: 2 additions & 2 deletions sdk/typescript/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@

export { AcpError, AgentCrashed, IncodeError, IncodeTimeout, ProtocolError, TaskFailed } from "./errors.js";
export type { ErrorDetails } from "./errors.js";
export { buildTaskArgv, parseTaskResult, runTask } from "./task.js";
export type { IncodePath, RunTaskOptions, TaskResult, TaskUsage } from "./task.js";
export { buildTaskArgv, parseTaskResult, runTask, streamTask } from "./task.js";
export type { IncodePath, RunTaskOptions, TaskEvent, TaskResult, TaskStream, TaskUsage } from "./task.js";
export { parseUpdate, PermissionRequest } from "./events.js";
export type {
AvailableCommands,
Expand Down
Loading
Loading