harnext 0.1.0__py3-none-any.whl

harnext-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: harnext
+Version: 0.1.0
+Summary: Python SDK for the harnext coding agent — subprocesses the harnext CLI with a Claude Agent SDK-compatible API.
+Author-email: Yasha Boroumand <yasha1boroumand@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/QualityUnit/harnext
+Project-URL: Repository, https://github.com/QualityUnit/harnext
+Project-URL: Documentation, https://github.com/QualityUnit/harnext/blob/main/sdk/python/README.md
+Project-URL: Issues, https://github.com/QualityUnit/harnext/issues
+Keywords: ai-agent,coding-agent,harnext,claude-agent-sdk,llm,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# harnext Python SDK
+
+Run the [harnext](https://github.com/QualityUnit/harnext) coding agent from Python. The SDK subprocesses
+the harnext CLI (`harnext -p --output-format stream-json`) and yields parsed
+messages, with an API that mirrors the
+[Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) for the
+supported surface.
+
+## Install
+
+```bash
+pip install harnext                  # from PyPI
+# or, from a checkout of this repo:
+pip install -e sdk/python
+
+# the harnext CLI must be installed too:
+npm install -g harnext               # or set HARNEXT_CLI_PATH to the CLI entry
+```
+
+The SDK locates the CLI via, in order: the `cli_path` option, the
+`HARNEXT_CLI_PATH` env var, or `harnext` on `PATH`. A `.js` path is run with
+`node`.
+
+## Quickstart
+
+```python
+import asyncio
+from harnext_sdk import query, HarnextAgentOptions, ResultMessage
+
+async def main():
+    async for message in query(
+        prompt="What files are in this directory?",
+        options=HarnextAgentOptions(allowed_tools=["Read", "Bash"]),
+    ):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+asyncio.run(main())
+```
+
+## Options (`HarnextAgentOptions`)
+
+Field names match `claude_agent_sdk.ClaudeAgentOptions`; `ClaudeAgentOptions` is
+exported as an alias so ported code runs unchanged.
+
+| Option | CLI flag | Notes |
+| --- | --- | --- |
+| `model` | `--model` | |
+| `system_prompt` | `--system-prompt` | |
+| `append_system_prompt` | `--append-system-prompt` | |
+| `cwd` | `--cwd` | |
+| `allowed_tools` | `--allowed-tools` | auto-approve list |
+| `disallowed_tools` | `--disallowed-tools` | blocked + hidden |
+| `permission_mode` | `--permission-mode` | `default`/`acceptEdits`/`plan`/`dontAsk`/`bypassPermissions` |
+| `max_turns` | `--max-turns` | |
+| `setting_sources` | `--setting-sources` | `user`/`project`/`local` → loads `CLAUDE.md` |
+| `add_dirs` | `--add-dir` | accepted; not yet enforced |
+| `fallback_model` | `--fallback-model` | accepted; reserved |
+| `sandbox` | `--sandbox` | accepted; **currently a no-op** in harnext |
+| `provider` | `--provider` | harnext extra |
+| `thinking` | `--thinking` | harnext extra |
+| `env` | (process env) | merged over `os.environ` |
+| `cli_path` | — | path to the CLI entry point |
+| `extra_args` | passthrough | `{"flag": "value"}` → `--flag value` |
+
+### Tool names
+
+Use the Claude names (`Read`, `Write`, `Edit`, `Bash`); they are matched
+case-insensitively against harnext's native tools and echoed back in PascalCase.
+
+## Messages
+
+`query()` yields `SystemMessage` (init), `AssistantMessage`, `UserMessage`
+(tool results), then a terminal `ResultMessage` with `subtype`
+(`success` / `error_max_turns` / `error_during_execution`), `result`,
+`num_turns`, `duration_ms`, `total_cost_usd`, and `usage`.
+
+## Tests
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+pytest                  # unit + stub-subprocess e2e
+HARNEXT_LIVE_E2E=1 pytest -k live   # live run against the real CLI (needs a provider key)
+```
+
+## Publishing to PyPI
+
+The package name on PyPI is **`harnext`** (import name `harnext_sdk`).
+
+### CI (recommended): trusted publishing
+
+`.github/workflows/publish-python-sdk.yml` builds, tests, and publishes via PyPI
+[trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no token
+stored in the repo).
+
+1. One-time: on PyPI (and TestPyPI) add a *pending publisher* for project
+   `harnext`, owner `QualityUnit`, repo `harnext`, workflow
+   `publish-python-sdk.yml`.
+2. Dry run to TestPyPI: run the workflow manually (`workflow_dispatch`, default
+   target `testpypi`).
+3. Release to PyPI: push a tag `python-v0.1.0` (independent of the CLI's `v*`
+   tags), or run the workflow manually with target `pypi`.
+
+### Manual
+
+```bash
+cd sdk/python
+python -m build                      # -> dist/*.whl, dist/*.tar.gz
+python -m twine check dist/*
+python -m twine upload dist/*        # needs a PyPI API token (TWINE_USERNAME=__token__)
+```
+
+Bump `version` in `pyproject.toml` and `__version__` in `harnext_sdk/__init__.py`
+together for each release.

harnext-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+harnext-0.1.0.dist-info/licenses/LICENSE,sha256=-8janKSe89TaFCYzzf_Fwth5QP365tf7ImAhjHilws8,1072
+harnext_sdk/__init__.py,sha256=AvgN_lYXLlaSv55klbBlTIf3rpK5BD-UlXFlCnUYxQw,1760
+harnext_sdk/_cli.py,sha256=NudQE2OdWk9k5cKfiOCI3KqT9GxUL15ajGjuAGo6wAs,3454
+harnext_sdk/_errors.py,sha256=xSG5RMAXXfuD244G9ThKRdlhzz7xCrEyTiWC1jCBVZM,828
+harnext_sdk/_parser.py,sha256=9VZhY_1hPsO1ws6V2dnhUlShBHTPYn5fyHuQgHG638g,3364
+harnext_sdk/_transport.py,sha256=Hed4RIIaas1nvvaXQVdx_5LxO1OEy0zJEoagSJWNipw,3671
+harnext_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+harnext_sdk/query.py,sha256=e5OJ9rMjiEB_hjOAcKEJY5wFK0sKYsik56y_UwIkelA,2038
+harnext_sdk/types.py,sha256=7USZPbYMfoEk3ctQv485TgCwKVdSllY5ThP-rTzSG4c,4016
+harnext-0.1.0.dist-info/METADATA,sha256=9-PxtRv8bnaovF96cZiVjjTemINsqRNZriVZD6-xO2Q,5458
+harnext-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+harnext-0.1.0.dist-info/top_level.txt,sha256=TN8r-fN3e_1e6QVKx9ulhuufp3SxhANJGgRhqSC2AGA,12
+harnext-0.1.0.dist-info/RECORD,,

harnext-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

harnext-0.1.0.dist-info/licenses/LICENSE

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

harnext-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+harnext_sdk

harnext_sdk/__init__.py

@@ -0,0 +1,79 @@
+"""harnext Python SDK.
+
+Run the harnext coding agent from Python by subprocessing its CLI, with an API
+that mirrors the Claude Agent SDK for the supported surface.
+
+    import asyncio
+    from harnext_sdk import query, HarnextAgentOptions, ResultMessage
+
+    async def main():
+        async for message in query(
+            prompt="What files are in this directory?",
+            options=HarnextAgentOptions(allowed_tools=["Read", "Bash"]),
+        ):
+            if isinstance(message, ResultMessage):
+                print(message.result)
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+from ._cli import build_command, resolve_cli_invocation
+from ._errors import (
+    CLINotFoundError,
+    HarnextSDKError,
+    MessageParseError,
+    ProcessError,
+)
+from ._parser import parse_line, parse_message
+from .query import query
+from .types import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    ContentBlock,
+    HarnextAgentOptions,
+    InputFormat,
+    Message,
+    OutputFormat,
+    PermissionMode,
+    ResultMessage,
+    SettingSource,
+    SystemMessage,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    UserMessage,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "query",
+    "HarnextAgentOptions",
+    "ClaudeAgentOptions",
+    "PermissionMode",
+    "OutputFormat",
+    "InputFormat",
+    "SettingSource",
+    "Message",
+    "SystemMessage",
+    "AssistantMessage",
+    "UserMessage",
+    "ResultMessage",
+    "ContentBlock",
+    "TextBlock",
+    "ThinkingBlock",
+    "ToolUseBlock",
+    "ToolResultBlock",
+    "HarnextSDKError",
+    "CLINotFoundError",
+    "ProcessError",
+    "MessageParseError",
+    "build_command",
+    "resolve_cli_invocation",
+    "parse_line",
+    "parse_message",
+    "__version__",
+]

harnext_sdk/_cli.py

@@ -0,0 +1,105 @@
+"""Locate the harnext CLI and translate options into CLI arguments."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from typing import Optional
+
+from ._errors import CLINotFoundError
+from .types import HarnextAgentOptions, InputFormat, OutputFormat
+
+
+def resolve_cli_invocation(cli_path: Optional[os.PathLike[str] | str]) -> list[str]:
+    """Return the argv prefix that launches the harnext CLI.
+
+    Resolution order:
+      1. explicit ``cli_path`` option,
+      2. ``HARNEXT_CLI_PATH`` environment variable,
+      3. ``harnext`` on ``PATH``.
+
+    A path ending in ``.js``/``.mjs`` is run with ``node``; one ending in
+    ``.py`` is run with the current interpreter (used by the test stub);
+    anything else is assumed directly executable.
+    """
+    candidate = cli_path or os.environ.get("HARNEXT_CLI_PATH")
+    if candidate:
+        path = os.fspath(candidate)
+        suffix = os.path.splitext(path)[1].lower()
+        if suffix in (".js", ".mjs"):
+            return ["node", path]
+        if suffix == ".py":
+            return [sys.executable, path]
+        return [path]
+
+    found = shutil.which("harnext")
+    if found:
+        return [found]
+
+    raise CLINotFoundError(
+        "Could not find the harnext CLI. Install it (npm i -g harnext), or set "
+        "the HARNEXT_CLI_PATH environment variable / cli_path option to the CLI "
+        "entry point."
+    )
+
+
+def build_command(
+    prompt: str,
+    options: HarnextAgentOptions,
+    *,
+    output_format: OutputFormat = "stream-json",
+    input_format: InputFormat = "text",
+) -> list[str]:
+    """Build the full argv for a one-shot ``harnext -p`` run."""
+    argv = resolve_cli_invocation(options.cli_path)
+    argv += ["-p", "--output-format", output_format]
+    if input_format != "text":
+        argv += ["--input-format", input_format]
+
+    if options.model:
+        argv += ["--model", options.model]
+    if options.fallback_model:
+        argv += ["--fallback-model", options.fallback_model]
+    if options.provider:
+        argv += ["--provider", options.provider]
+    if options.thinking:
+        argv += ["--thinking", options.thinking]
+
+    if options.system_prompt is not None:
+        argv += ["--system-prompt", options.system_prompt]
+    if options.append_system_prompt is not None:
+        argv += ["--append-system-prompt", options.append_system_prompt]
+
+    if options.cwd is not None:
+        argv += ["--cwd", os.fspath(options.cwd)]
+    if options.permission_mode:
+        argv += ["--permission-mode", options.permission_mode]
+    if options.max_turns is not None:
+        argv += ["--max-turns", str(options.max_turns)]
+
+    for tool in options.allowed_tools or []:
+        argv += ["--allowed-tools", tool]
+    for tool in options.disallowed_tools or []:
+        argv += ["--disallowed-tools", tool]
+    for source in options.setting_sources or []:
+        argv += ["--setting-sources", source]
+    for directory in options.add_dirs or []:
+        argv += ["--add-dir", os.fspath(directory)]
+
+    if options.sandbox is not None:
+        argv += ["--sandbox", json.dumps(options.sandbox)]
+
+    for key, value in (options.extra_args or {}).items():
+        flag = f"--{key}"
+        if value is None:
+            argv.append(flag)
+        else:
+            argv += [flag, value]
+
+    # Text input: the prompt is the trailing positional argument.
+    if input_format == "text":
+        argv.append(prompt)
+
+    return argv

harnext_sdk/_errors.py

@@ -0,0 +1,28 @@
+"""Exceptions raised by the harnext Python SDK."""
+
+from __future__ import annotations
+
+
+class HarnextSDKError(Exception):
+    """Base class for all SDK errors."""
+
+
+class CLINotFoundError(HarnextSDKError):
+    """The harnext CLI executable could not be located."""
+
+
+class ProcessError(HarnextSDKError):
+    """The CLI subprocess exited with a non-zero status and no result message."""
+
+    def __init__(self, message: str, *, exit_code: int | None = None, stderr: str = "") -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.stderr = stderr
+
+
+class MessageParseError(HarnextSDKError):
+    """A line emitted by the CLI could not be parsed as a known message."""
+
+    def __init__(self, message: str, *, line: str = "") -> None:
+        super().__init__(message)
+        self.line = line

harnext_sdk/_parser.py

@@ -0,0 +1,109 @@
+"""Parse the CLI's stream-json envelopes into message dataclasses."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from ._errors import MessageParseError
+from .types import (
+    AssistantMessage,
+    ContentBlock,
+    Message,
+    ResultMessage,
+    SystemMessage,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    UserMessage,
+)
+
+
+def _parse_content_blocks(content: Any) -> list[ContentBlock]:
+    blocks: list[ContentBlock] = []
+    if not isinstance(content, list):
+        return blocks
+    for raw in content:
+        if not isinstance(raw, dict):
+            continue
+        block_type = raw.get("type")
+        if block_type == "text":
+            blocks.append(TextBlock(text=raw.get("text", "")))
+        elif block_type == "thinking":
+            blocks.append(ThinkingBlock(thinking=raw.get("thinking", "")))
+        elif block_type == "tool_use":
+            blocks.append(
+                ToolUseBlock(
+                    id=raw.get("id", ""),
+                    name=raw.get("name", ""),
+                    input=raw.get("input", {}) or {},
+                )
+            )
+        elif block_type == "tool_result":
+            blocks.append(
+                ToolResultBlock(
+                    tool_use_id=raw.get("tool_use_id", ""),
+                    content=raw.get("content"),
+                    is_error=bool(raw.get("is_error", False)),
+                )
+            )
+    return blocks
+
+
+def parse_message(obj: dict[str, Any]) -> Optional[Message]:
+    """Convert a decoded envelope dict into a message, or ``None`` if unknown."""
+    msg_type = obj.get("type")
+    session_id = obj.get("session_id")
+
+    if msg_type == "system":
+        return SystemMessage(
+            subtype=obj.get("subtype", ""),
+            data=obj,
+            session_id=session_id,
+        )
+
+    if msg_type == "assistant":
+        message = obj.get("message", {}) or {}
+        return AssistantMessage(
+            content=_parse_content_blocks(message.get("content")),
+            model=message.get("model"),
+            usage=message.get("usage"),
+            stop_reason=message.get("stop_reason"),
+            session_id=session_id,
+        )
+
+    if msg_type == "user":
+        message = obj.get("message", {}) or {}
+        return UserMessage(
+            content=_parse_content_blocks(message.get("content")),
+            session_id=session_id,
+        )
+
+    if msg_type == "result":
+        return ResultMessage(
+            subtype=obj.get("subtype", ""),
+            is_error=bool(obj.get("is_error", False)),
+            result=obj.get("result"),
+            session_id=session_id,
+            num_turns=int(obj.get("num_turns", 0)),
+            duration_ms=int(obj.get("duration_ms", 0)),
+            total_cost_usd=obj.get("total_cost_usd"),
+            usage=obj.get("usage", {}) or {},
+        )
+
+    return None
+
+
+def parse_line(line: str) -> Optional[Message]:
+    """Decode a single NDJSON line into a message (``None`` for blank/unknown)."""
+    stripped = line.strip()
+    if not stripped:
+        return None
+    try:
+        obj = json.loads(stripped)
+    except json.JSONDecodeError as exc:
+        raise MessageParseError(f"Invalid JSON from CLI: {exc}", line=stripped) from exc
+    if not isinstance(obj, dict):
+        return None
+    return parse_message(obj)

harnext_sdk/_transport.py

@@ -0,0 +1,99 @@
+"""Async subprocess transport: spawn the harnext CLI, stream its NDJSON stdout."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import AsyncIterator, Callable, Optional
+
+from ._errors import ProcessError
+
+_DEFAULT_BUFFER_LIMIT = 10 * 1024 * 1024  # 10 MiB per stdout line
+
+
+class SubprocessCLITransport:
+    """Spawns the CLI and yields decoded stdout lines.
+
+    Use as an async context manager::
+
+        transport = SubprocessCLITransport(command=argv, cwd=cwd)
+        async with transport:
+            async for line in transport.read_lines():
+                ...
+    """
+
+    def __init__(
+        self,
+        *,
+        command: list[str],
+        cwd: Optional[os.PathLike[str] | str] = None,
+        env: Optional[dict[str, str]] = None,
+        stderr_callback: Optional[Callable[[str], None]] = None,
+        buffer_limit: Optional[int] = None,
+    ) -> None:
+        self._command = command
+        self._cwd = os.fspath(cwd) if cwd is not None else None
+        self._env = env
+        self._stderr_callback = stderr_callback
+        self._buffer_limit = buffer_limit or _DEFAULT_BUFFER_LIMIT
+        self._process: Optional[asyncio.subprocess.Process] = None
+        self._stderr_task: Optional[asyncio.Task[None]] = None
+        self._stderr_lines: list[str] = []
+        self._saw_result = False
+
+    async def __aenter__(self) -> "SubprocessCLITransport":
+        self._process = await asyncio.create_subprocess_exec(
+            *self._command,
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=self._cwd,
+            env=self._env,
+            limit=self._buffer_limit,
+        )
+        self._stderr_task = asyncio.ensure_future(self._drain_stderr())
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        process = self._process
+        if process is None:
+            return
+
+        if exc_type is not None and process.returncode is None:
+            # The consumer bailed out early — terminate the child.
+            try:
+                process.terminate()
+            except ProcessLookupError:
+                pass
+
+        await process.wait()
+        if self._stderr_task is not None:
+            await self._stderr_task
+
+        # Surface a hard failure only when the CLI exited non-zero *and* never
+        # produced a result envelope (which already carries error details).
+        if exc_type is None and process.returncode not in (0, None) and not self._saw_result:
+            stderr_text = "\n".join(self._stderr_lines)
+            raise ProcessError(
+                f"harnext CLI exited with code {process.returncode}.",
+                exit_code=process.returncode,
+                stderr=stderr_text,
+            )
+
+    async def _drain_stderr(self) -> None:
+        assert self._process is not None and self._process.stderr is not None
+        async for raw in self._process.stderr:
+            text = raw.decode("utf-8", errors="replace").rstrip("\n")
+            self._stderr_lines.append(text)
+            if self._stderr_callback is not None:
+                self._stderr_callback(text)
+
+    async def read_lines(self) -> AsyncIterator[str]:
+        """Yield each stdout line (without the trailing newline)."""
+        assert self._process is not None and self._process.stdout is not None
+        async for raw in self._process.stdout:
+            yield raw.decode("utf-8", errors="replace").rstrip("\n")
+
+    def mark_result_seen(self) -> None:
+        """Record that a result envelope arrived (suppresses exit-code errors)."""
+        self._saw_result = True

harnext_sdk/query.py

@@ -0,0 +1,63 @@
+"""The ``query()`` entry point: run harnext once and stream parsed messages."""
+
+from __future__ import annotations
+
+import os
+from typing import AsyncIterator, Optional
+
+from ._cli import build_command
+from ._parser import parse_line
+from ._transport import SubprocessCLITransport
+from .types import HarnextAgentOptions, Message, ResultMessage
+
+
+def _merge_env(options: HarnextAgentOptions) -> Optional[dict[str, str]]:
+    # Inherit the full environment by default (so provider API keys flow
+    # through). When the caller supplies env vars, layer them on top.
+    if not options.env:
+        return None
+    return {**os.environ, **options.env}
+
+
+async def query(
+    *,
+    prompt: str,
+    options: Optional[HarnextAgentOptions] = None,
+) -> AsyncIterator[Message]:
+    """Run a one-shot harnext task and yield messages as they arrive.
+
+    Mirrors ``claude_agent_sdk.query``: spawns the harnext CLI as a subprocess
+    with ``--output-format stream-json`` and yields
+    :class:`~harnext_sdk.types.SystemMessage`,
+    :class:`~harnext_sdk.types.AssistantMessage`,
+    :class:`~harnext_sdk.types.UserMessage`, and a terminal
+    :class:`~harnext_sdk.types.ResultMessage`.
+
+    Example::
+
+        async for message in query(
+            prompt="List the files here",
+            options=HarnextAgentOptions(allowed_tools=["Read", "Bash"]),
+        ):
+            if isinstance(message, ResultMessage):
+                print(message.result)
+    """
+    opts = options or HarnextAgentOptions()
+    command = build_command(prompt, opts)
+
+    transport = SubprocessCLITransport(
+        command=command,
+        cwd=opts.cwd,
+        env=_merge_env(opts),
+        stderr_callback=opts.stderr,
+        buffer_limit=opts.max_buffer_size,
+    )
+
+    async with transport:
+        async for line in transport.read_lines():
+            message = parse_line(line)
+            if message is None:
+                continue
+            if isinstance(message, ResultMessage):
+                transport.mark_result_seen()
+            yield message

harnext_sdk/types.py

@@ -0,0 +1,142 @@
+"""Public types for the harnext Python SDK.
+
+The option and message shapes mirror the Claude Agent SDK one-to-one for the
+surface we support, so existing ``claude_agent_sdk`` code ports over by swapping
+the import. ``ClaudeAgentOptions`` is exported as an alias of
+``HarnextAgentOptions`` for drop-in use.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Callable, Literal, Optional, Union
+
+PermissionMode = Literal["default", "acceptEdits", "plan", "dontAsk", "bypassPermissions"]
+OutputFormat = Literal["text", "json", "stream-json"]
+InputFormat = Literal["text", "stream-json"]
+SettingSource = Literal["user", "project", "local"]
+
+
+@dataclass
+class HarnextAgentOptions:
+    """Configuration for a :func:`harnext_sdk.query` run.
+
+    Field names match ``claude_agent_sdk.ClaudeAgentOptions`` for the supported
+    surface. Options the harness does not yet act on (``sandbox``,
+    ``fallback_model``, ``add_dirs``) are accepted so caller code is unchanged.
+    """
+
+    # --- Tools ---
+    allowed_tools: list[str] = field(default_factory=list)
+    disallowed_tools: list[str] = field(default_factory=list)
+
+    # --- System prompt ---
+    system_prompt: Optional[str] = None
+    append_system_prompt: Optional[str] = None
+
+    # --- Permissions ---
+    permission_mode: Optional[PermissionMode] = None
+
+    # --- Limits ---
+    max_turns: Optional[int] = None
+
+    # --- Model ---
+    model: Optional[str] = None
+    fallback_model: Optional[str] = None
+    # harnext extras (no Claude equivalent):
+    provider: Optional[str] = None
+    thinking: Optional[str] = None
+
+    # --- Environment / filesystem ---
+    cwd: Optional[Union[str, os.PathLike[str]]] = None
+    add_dirs: list[Union[str, os.PathLike[str]]] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    setting_sources: Optional[list[SettingSource]] = None
+
+    # --- Sandbox (accepted; currently a no-op in harnext) ---
+    sandbox: Optional[dict[str, Any]] = None
+
+    # --- Transport / advanced ---
+    cli_path: Optional[Union[str, os.PathLike[str]]] = None
+    extra_args: dict[str, Optional[str]] = field(default_factory=dict)
+    stderr: Optional[Callable[[str], None]] = None
+    max_buffer_size: Optional[int] = None
+
+
+# Drop-in alias for ported claude_agent_sdk code.
+ClaudeAgentOptions = HarnextAgentOptions
+
+
+# --------------------------------------------------------------------------- #
+# Content blocks
+# --------------------------------------------------------------------------- #
+@dataclass
+class TextBlock:
+    text: str
+
+
+@dataclass
+class ThinkingBlock:
+    thinking: str
+
+
+@dataclass
+class ToolUseBlock:
+    id: str
+    name: str
+    input: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ToolResultBlock:
+    tool_use_id: str
+    content: Any = None
+    is_error: bool = False
+
+
+ContentBlock = Union[TextBlock, ThinkingBlock, ToolUseBlock, ToolResultBlock]
+
+
+# --------------------------------------------------------------------------- #
+# Messages
+# --------------------------------------------------------------------------- #
+@dataclass
+class SystemMessage:
+    """A system event, e.g. the ``init`` envelope at session start."""
+
+    subtype: str
+    data: dict[str, Any]
+    session_id: Optional[str] = None
+
+
+@dataclass
+class AssistantMessage:
+    content: list[ContentBlock]
+    model: Optional[str] = None
+    usage: Optional[dict[str, Any]] = None
+    stop_reason: Optional[str] = None
+    session_id: Optional[str] = None
+
+
+@dataclass
+class UserMessage:
+    """User-role message; in practice carries tool_result blocks."""
+
+    content: list[ContentBlock]
+    session_id: Optional[str] = None
+
+
+@dataclass
+class ResultMessage:
+    subtype: str
+    is_error: bool
+    result: Optional[str]
+    session_id: Optional[str]
+    num_turns: int
+    duration_ms: int
+    total_cost_usd: Optional[float]
+    usage: dict[str, Any]
+
+
+Message = Union[SystemMessage, AssistantMessage, UserMessage, ResultMessage]