ai-hats-client 0.2.0__tar.gz

ai_hats_client-0.2.0/.gitignore

@@ -0,0 +1,54 @@
+_version.py
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+*.log
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# macOS finder metadata
+.DS_Store
+
+# uv.lock — local dev tool artifact, ai-hats is a library installed via pip
+uv.lock
+
+# Real-session fixtures — recorded from a developer's local Claude Code session,
+# contain absolute home paths, real sessionId/requestId, subscription metadata,
+# and unredacted user prompts. Tests that consume them auto-skip when absent.
+# Generate locally for debugging; never commit. See HATS-343.
+tests/fixtures/real_conversation.jsonl
+tests/fixtures/real_trace.log
+
+# ai-hats runtime (generated per-project)
+.agent/
+.githooks/
+.gitlog/
+ai-hats.yaml
+profile.json       # legacy, migrated to ai-hats.yaml
+profile.json.bak
+GEMINI.md
+CLAUDE.md
+.claude/skills/
+.claude/scheduled_tasks.lock
+.claude/settings.local.json
+.claude/settings.json
+.envrc
+.gemini/
+.cline/skills/
+.cline/plugins/
+.agy/
+
+.agent/ai-hats/

ai_hats_client-0.2.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to `ai-hats-client` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## [0.2.0]
+
+### Added
+
+- The stub claude (`ai_hats_client.testing`) follows claude 2.1.283 further:
+  - every prompt line gets `command_lifecycle` on the wire (`queued`, `started`,
+    `completed`); a prompt folded into a running turn is echoed before it is
+    started;
+  - slash commands: `/model`, `/context`, `/usage` and `/rename` are answered by
+    a `<synthetic>` response before their echo, and `/tui`, `/login` and the
+    other refused ones get "isn't available in this environment" and no echo;
+  - `/clear` writes `conversation_reset`, then goes on under a new session id
+    and in a new transcript, and forgets the previous prompt.
+
+## [0.1.0]
+
+### Added
+
+- `HeadlessSession`: start `ai-hats headless`, read its `headless/v1` header, send
+  a `prompt`, wait for the `turn_ended` that carries the prompt's id, and close or
+  abort the session. Every wait is bounded.
+- `answer(call_id, decision, message=, answers=)` decides a question the
+  session put; `interrupt()` stops the running turn and keeps the session.
+- A turn wait takes `on_question`. A question stays offered until it is answered,
+  its handler returns, or its call gets a result. With no handler the wait raises
+  `QuestionPending` instead of waiting out its bound. `tool_call(call_id)` returns
+  the call a question is about.
+- A command the holder would refuse raises `ValueError` before it is sent; one the
+  holder does not run (per `header.commands`), or any command after the session
+  ended, raises `HeadlessError`.
+- Leaving a `with` block terminates a holder that does not end within
+  `close_timeout`, then raises the timeout.
+- Typed: the wheel carries `py.typed`.
+- `ai_hats_client.testing`: a stand-in `claude` binary that speaks the
+  stream-json wire, so tests of a client run with no model and no login. It asks
+  questions (`@ask`, `@askq`, `@plan`) and runs long turns an interrupt can cut
+  (`@slow`, `@slowtool`). It drifts off the wire (`@drift`), hits the quota
+  (`@quota <status>`, reset at `QUOTA_RESETS_AT`), dies by a signal (`@kill`,
+  `@ignore-term`), and reports itself logged out under `LOGGED_OUT_ENV`.

ai_hats_client-0.2.0/LICENSE

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

ai_hats_client-0.2.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: ai-hats-client
+Version: 0.2.0
+Summary: Drive an ai-hats headless session over its stdin and stdout: turns, answers to its questions, interrupts.
+Project-URL: Homepage, https://github.com/muratovv/ai-hats
+Project-URL: Repository, https://github.com/muratovv/ai-hats
+Project-URL: Changelog, https://github.com/muratovv/ai-hats/blob/master/packages/ai-hats-client/CHANGELOG.md
+Author-email: muratovv <f@muratovv.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-hats,claude,client,headless,session
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# ai-hats-client
+
+Drive an `ai-hats headless` session from a program: send turns, wait for each
+one to end, and read everything the session did.
+
+`ai-hats headless` runs a role's interactive session with no terminal. Its stdin
+takes commands, one JSON object per line (`commands/v1`). Its stdout opens with a
+header line (`headless/v1`) and then copies the session's event log byte for
+byte (`events/v1`). Its exit code says how the session ended. This package speaks
+that contract and nothing else. It uses only the standard library and imports
+nothing from ai-hats.
+
+```python
+from ai_hats_client import HeadlessSession
+
+with HeadlessSession.start(["ai-hats", "headless", "-r", "maintainer"]) as s:
+    first = s.turn("remember the word KIWI")
+    second = s.turn("which word?")
+    end = s.close()
+assert "KIWI" in second.text and end.code == 0
+```
+
+- `HeadlessSession.start(argv, cwd=, env=)` launches the holder and reads the
+  header. If the holder refuses before the start, it raises `SessionEnded`, which
+  carries the exit code.
+- `prompt(text, id=None)` sends a turn and returns its id. `turn_for(id)` waits
+  for the `turn_ended` event that lists that id. `turn(text)` does both.
+- `close()` closes stdin, which tells the holder to finish its turns and exit. It
+  then reads to the end and returns an `Exit` with the code, every event and the
+  holder's stderr. `terminate()` signals the holder instead.
+- Leaving a `with` block closes the session. If the session does not end within
+  `start(..., close_timeout=60)`, the holder is terminated and the
+  `HeadlessTimeout` is raised, so no session keeps spending turns.
+
+Every wait has a bound. Every error carries what was read so far and the tail of
+the holder's stderr.
+
+- A command the holder would refuse raises `ValueError` before it is sent: empty
+  text, an `id` that is not a lowercase canonical UUID, a `decision` other than
+  `allow` or `deny`.
+- A command the holder does not run raises `HeadlessError`, and so does any
+  command after the session has ended. The holder lists what it runs in
+  `header.commands`.
+- `prompt()`, `answer()` and `interrupt()` may be called from another thread, for
+  instance a watchdog that interrupts a turn while the main thread waits on it.
+  The waits themselves belong to one thread.
+
+## Questions and interrupts
+
+A session asks its stdin owner what it would ask a person at the terminal: a
+gate's `ask`, a consent point, claude's own permission prompt, leaving plan mode,
+the model's own question. Each question arrives as a `person_asked` event with a
+`call_id`, and the call waits for your answer.
+
+```python
+def decide(question):
+    s.answer(question["call_id"], "allow")          # or "deny", message="why"
+
+turn = s.turn("push the branch", on_question=decide)
+```
+
+- A turn wait hands each question to `on_question`. Without a handler it
+  raises `QuestionPending` instead of waiting out its bound. Answer
+  `pending.question["call_id"]` and wait again: nothing read so far is lost.
+- `answer(call_id, "allow", answers={"<question>": "<answer>"})` answers a
+  question the model asked with `AskUserQuestion`. `tool_call(call_id)` returns
+  the call the question is about, with the questions and their options in its
+  `input`.
+- A question stays offered until you answer it, its handler returns, or its call
+  gets a result: a handler that raised sees it again on the next wait.
+- The first answer on a call id wins. The holder refuses the rest and logs a
+  `command_rejected` signal for each.
+- `interrupt()` stops the running turn and keeps the session. The turn still
+  ends with its `turn_ended`, and a question it had open is closed.
+
+The holder never times out a question. If you will not wait, answer `deny`.
+
+The client is synchronous. A caller that needs asyncio runs it in a thread.
+
+## Testing without a model
+
+`ai_hats_client.testing` has a stand-in `claude` binary that speaks the same wire.
+Tests that use it need no model and no login:
+
+```python
+import os
+
+from ai_hats_client.testing import install
+
+stub = install(tmp_path)  # writes tmp_path/stub-bin/claude
+env = {**os.environ, **stub.env(os.environ["PATH"])}
+```
+
+Each prompt's text picks what the stub does. The directives are listed in the
+module docstring of `ai_hats_client.testing.stub_claude`.

ai_hats_client-0.2.0/README.md

@@ -0,0 +1,95 @@
+# ai-hats-client
+
+Drive an `ai-hats headless` session from a program: send turns, wait for each
+one to end, and read everything the session did.
+
+`ai-hats headless` runs a role's interactive session with no terminal. Its stdin
+takes commands, one JSON object per line (`commands/v1`). Its stdout opens with a
+header line (`headless/v1`) and then copies the session's event log byte for
+byte (`events/v1`). Its exit code says how the session ended. This package speaks
+that contract and nothing else. It uses only the standard library and imports
+nothing from ai-hats.
+
+```python
+from ai_hats_client import HeadlessSession
+
+with HeadlessSession.start(["ai-hats", "headless", "-r", "maintainer"]) as s:
+    first = s.turn("remember the word KIWI")
+    second = s.turn("which word?")
+    end = s.close()
+assert "KIWI" in second.text and end.code == 0
+```
+
+- `HeadlessSession.start(argv, cwd=, env=)` launches the holder and reads the
+  header. If the holder refuses before the start, it raises `SessionEnded`, which
+  carries the exit code.
+- `prompt(text, id=None)` sends a turn and returns its id. `turn_for(id)` waits
+  for the `turn_ended` event that lists that id. `turn(text)` does both.
+- `close()` closes stdin, which tells the holder to finish its turns and exit. It
+  then reads to the end and returns an `Exit` with the code, every event and the
+  holder's stderr. `terminate()` signals the holder instead.
+- Leaving a `with` block closes the session. If the session does not end within
+  `start(..., close_timeout=60)`, the holder is terminated and the
+  `HeadlessTimeout` is raised, so no session keeps spending turns.
+
+Every wait has a bound. Every error carries what was read so far and the tail of
+the holder's stderr.
+
+- A command the holder would refuse raises `ValueError` before it is sent: empty
+  text, an `id` that is not a lowercase canonical UUID, a `decision` other than
+  `allow` or `deny`.
+- A command the holder does not run raises `HeadlessError`, and so does any
+  command after the session has ended. The holder lists what it runs in
+  `header.commands`.
+- `prompt()`, `answer()` and `interrupt()` may be called from another thread, for
+  instance a watchdog that interrupts a turn while the main thread waits on it.
+  The waits themselves belong to one thread.
+
+## Questions and interrupts
+
+A session asks its stdin owner what it would ask a person at the terminal: a
+gate's `ask`, a consent point, claude's own permission prompt, leaving plan mode,
+the model's own question. Each question arrives as a `person_asked` event with a
+`call_id`, and the call waits for your answer.
+
+```python
+def decide(question):
+    s.answer(question["call_id"], "allow")          # or "deny", message="why"
+
+turn = s.turn("push the branch", on_question=decide)
+```
+
+- A turn wait hands each question to `on_question`. Without a handler it
+  raises `QuestionPending` instead of waiting out its bound. Answer
+  `pending.question["call_id"]` and wait again: nothing read so far is lost.
+- `answer(call_id, "allow", answers={"<question>": "<answer>"})` answers a
+  question the model asked with `AskUserQuestion`. `tool_call(call_id)` returns
+  the call the question is about, with the questions and their options in its
+  `input`.
+- A question stays offered until you answer it, its handler returns, or its call
+  gets a result: a handler that raised sees it again on the next wait.
+- The first answer on a call id wins. The holder refuses the rest and logs a
+  `command_rejected` signal for each.
+- `interrupt()` stops the running turn and keeps the session. The turn still
+  ends with its `turn_ended`, and a question it had open is closed.
+
+The holder never times out a question. If you will not wait, answer `deny`.
+
+The client is synchronous. A caller that needs asyncio runs it in a thread.
+
+## Testing without a model
+
+`ai_hats_client.testing` has a stand-in `claude` binary that speaks the same wire.
+Tests that use it need no model and no login:
+
+```python
+import os
+
+from ai_hats_client.testing import install
+
+stub = install(tmp_path)  # writes tmp_path/stub-bin/claude
+env = {**os.environ, **stub.env(os.environ["PATH"])}
+```
+
+Each prompt's text picks what the stub does. The directives are listed in the
+module docstring of `ai_hats_client.testing.stub_claude`.

ai_hats_client-0.2.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ai-hats-client"
+version = "0.2.0"
+description = "Drive an ai-hats headless session over its stdin and stdout: turns, answers to its questions, interrupts."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "muratovv", email = "f@muratovv.me" }, # ai-hats: allow-secret
+]
+keywords = ["headless", "session", "client", "claude", "ai-hats"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+# Standard library only: a client relies on the holder's pipes and exit code, never on ai-hats.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/muratovv/ai-hats"
+Repository = "https://github.com/muratovv/ai-hats"
+Changelog = "https://github.com/muratovv/ai-hats/blob/master/packages/ai-hats-client/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ai_hats_client"]

ai_hats_client-0.2.0/src/ai_hats_client/__init__.py

@@ -0,0 +1,35 @@
+"""Drive an ``ai-hats headless`` session through its pipes, knowing nothing but its contract."""
+
+from .session import (
+    Event,
+    Exit,
+    Header,
+    HeadlessError,
+    HeadlessSession,
+    HeadlessTimeout,
+    OnQuestion,
+    ProtocolError,
+    QuestionPending,
+    SessionEnded,
+    Turn,
+    answer_command,
+    interrupt_command,
+    prompt_command,
+)
+
+__all__ = [
+    "Event",
+    "Exit",
+    "Header",
+    "HeadlessError",
+    "HeadlessSession",
+    "HeadlessTimeout",
+    "OnQuestion",
+    "ProtocolError",
+    "QuestionPending",
+    "SessionEnded",
+    "Turn",
+    "answer_command",
+    "interrupt_command",
+    "prompt_command",
+]