tokenloop 0.1.2__tar.gz → 0.1.3__tar.gz

{tokenloop-0.1.2 → tokenloop-0.1.3}/.gitignore

@@ -13,4 +13,5 @@ wheels/
 .env
 .claude/
 .ruff_cache/
-.pytest_cache/
+.pytest_cache/
+.pypi.md

tokenloop-0.1.3/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: tokenloop
+Version: 0.1.3
+Summary: Add your description here
+Project-URL: Homepage, https://github.com/RahulDas-dev/loop
+Project-URL: Repository, https://github.com/RahulDas-dev/loop
+Project-URL: Releases, https://github.com/RahulDas-dev/loop/releases
+Author-email: RahulDas-dev <r.das699@gmail.com>
+Requires-Python: >=3.10
+Requires-Dist: ag-ui-protocol>=0.1.20
+Requires-Dist: anthropic>=0.125.0
+Requires-Dist: mcp>=2.0.0
+Requires-Dist: openai>=2.48.0
+Description-Content-Type: text/markdown
+
+# ⚡ tokenloop
+
+[![PyPI](https://img.shields.io/pypi/v/tokenloop)](https://pypi.org/project/tokenloop/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/tokenloop/)
+
+A protocol-driven, model-agnostic agent loop for Python. `AgentLoop` runs
+the prompt → model → tool-call → model loop for you — streaming, retries,
+human-in-the-loop pauses, history compaction, and session persistence
+included — while every swappable piece (provider, tool, guardrail, approver,
+compressor, session store) is a plain `typing.Protocol`, not a base class
+you're forced to inherit from.
+
+`tokenloop` is also an active, ongoing **parity port of a companion Rust
+crate** — much of the module layout is deliberately file-for-file with its
+Rust counterpart (`core/loop.py` ↔ `agent/agent.rs`, `core/stream.py` ↔
+`agent/stream.rs`, `core/registry.py` ↔ `run/registry.rs`, and so on), which
+is why you'll find "Python counterpart of ..." in a lot of the source
+docstrings. A few Rust features are deliberately **not** ported yet — see
+[Deliberately not ported](#deliberately-not-ported-yet) below.
+
+## Philosophy
+
+- **Protocol-driven, not inheritance-driven.** `LLMProvider`, `Tool`,
+  `Guardrail`, `Approver`, `Compressor`, `SessionService`, `ToolHook` — every
+  one of these is a structural `Protocol`. Anything with the right shape
+  works; you never subclass a framework base class to plug something in.
+- **`AgentLoop` is stateless; `Session` isn't.** Build one `AgentLoop`, reuse
+  it for every conversation and every concurrent run. All per-conversation
+  state — history, app/user/tmp state, past runs — lives in a `Session`,
+  loaded and saved through a `SessionService` keyed by `session_id`. Nothing
+  conversational is ever held on the `AgentLoop` object itself.
+- **Two different lifetimes, two different objects.** `RunContext` is the
+  *live* object threaded through hooks and tools during one `run()`/
+  `astream()` call — it's never persisted. `RunRecord` is what actually gets
+  written to `Session.runs` once a run finishes: an immutable summary, not a
+  working object.
+- **Every event tells you who and when.** All 20+ event types share one
+  `BaseEvent` (`run_id`, `session_id`, `agent_id`, `created_at`) — full run
+  lifecycle (`RunStarted`/`RunPaused`/`RunError`/`RunCompleted`), per-turn
+  model events, and per-tool-call events, all correlatable.
+
+## Features
+
+- **Core loop** — `AgentLoop` runs a real, working turn loop
+  (`astream()`; `run()` just drains it and returns the final message):
+  automatic retry with exponential backoff on 408/409/429/5xx, best-effort
+  history compaction, a `RunControlService` for pausing/resuming/cancelling
+  a run by `run_id`, and a working interactive CLI (`agent.as_cli()`) for
+  local dev/testing.
+- **Providers** — `LLMProvider` is a `Protocol`; ships with working
+  `AnthropicProvider` and `OpenAIProvider` implementations, both lazily
+  imported so you only pay for the SDK you actually use.
+- **Tools** — `FunctionTool` builds a JSON Schema straight from a plain
+  Python function's signature (stdlib `inspect`/`typing` reflection, no
+  Pydantic). Tool calls in one turn dispatch concurrently. Ships with four
+  builtin tools: `update_state`, `BashTool`, `Read`, and `FileStore`.
+- **Human-in-the-Loop** — a tool can pause a run for `Confirmation`,
+  `InputRequired`, or `ExternalExecution`; an `Approver` can `ALLOW`/`DENY`/
+  `AUDIT` any tool call; `RunMode.INTERACTIVE` vs `NON_INTERACTIVE` controls
+  whether pausing is even allowed; full resume support built in.
+- **Image input** — attach `ImageBase64`/`ImageUrl` sources to a user turn
+  (`image_from_file()` reads and encodes a local file); both providers
+  serialize them into their own content-block format, and context
+  compaction accounts for their token cost.
+- **Guardrails** — `pre_hooks` validate the user's message *before* the
+  model is ever called; `post_hooks` validate the assistant's response.
+  Both also get a fire-and-forget `on_completion` for logging/eval that
+  never adds latency to the run.
+- **Compression** — `SimpleCompressor` trims oldest messages under a token
+  budget (tool-call/result pairing preserved); `HistoryWindow` separately
+  caps the *persisted* session history by message or run count.
+- **Skills** — disk-based, compatible with Anthropic's Agent Skills layout
+  (a `SKILL.md` per skill); every discovered skill resolves into a single
+  `invoke_skill` meta-tool rather than one tool per skill.
+- **MCP** — a client-side bridge (`MCPToolProvider`/`MCPManager`) adapts any
+  MCP server's tools onto the same `Tool` protocol as everything else.
+- **Sessions** — `SessionService` protocol, with an `InMemorySessionService`
+  included (single-process — bring your own for multi-replica deployments).
+- **State** — a standalone `State` utility with delta tracking and an RFC
+  6902 JSON-Patch `diff()`, for building your own state-sync pipeline
+  (not wired into `RunContext`/the AG-UI bridge, which stay plain dicts and
+  full-snapshot-only today).
+- **Streaming & observability** — every run emits a typed `LoopEvent`
+  stream; an `AGUIBridge` translates it into AG-UI protocol events for
+  frontend consumption, and a zero-dependency `SpanCollector` turns it into
+  spans for whatever tracing backend you want to export to.
+
+## Installation
+
+```bash
+pip install tokenloop
+```
+
+`ag-ui-protocol`, `anthropic`, `mcp`, and `openai` are currently all
+unconditional dependencies — one install gets you both providers and the
+AG-UI/MCP protocol surface. (No optional extras exist yet.)
+
+## Quickstart
+
+```python
+import asyncio
+import os
+
+from tokenloop import AgentLoop
+from tokenloop.provider.anthropic import AnthropicProvider
+
+
+async def main() -> None:
+    agent = AgentLoop(
+        AnthropicProvider(model=os.environ["ANTHROPIC_MODEL"]),
+        instruction="You are a concise, helpful assistant.",
+    )
+
+    # Interactive REPL, good for trying things out:
+    await agent.as_cli(None)
+
+    # Or drive it programmatically:
+    # message = await agent.run("session-1", "run-1", "What's 2 + 2?")
+    # print(message.content)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Adding a tool is just a plain Python function:
+
+```python
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    ...
+
+agent.add_tool(get_weather)
+```
+
+See `examples/` for more — tool calling, session state, streaming events,
+and a skills-based agent.
+
+## Testing
+
+```bash
+uv run pytest -v      # 35 passed, 0 failed, 0 skipped
+uv run ruff check     # all checks pass
+uv run python examples/smoke_test.py   # offline, no API key needed
+```
+
+The test suite covers HITL resume (all three pause kinds), a HITL-skipped
+tool not aborting the rest of its batch, `RunControlService`
+(pause/resume/cancel), image serialization for both providers, and
+`State`'s delta-tracking/diff behavior. `examples/smoke_test.py` exercises
+the tool-call round trip and a blocking guardrail end-to-end against a fake
+provider — no network or API key required.
+
+## Documentation
+
+There's no separate docs site yet — this README is it, plus:
+
+- [`docs/HITL_PARITY.md`](docs/HITL_PARITY.md) — a deep dive into the
+  HITL/`RunControlService` design and its parity with the Rust crate.
+- [Repository](https://github.com/RahulDas-dev/loop)
+- [Releases](https://github.com/RahulDas-dev/loop/releases)
+
+## Deliberately not ported (yet)
+
+A few things the companion Rust crate has that this port doesn't, by
+explicit scope decision (see the relevant source docstrings):
+
+- LLM-summarizing compaction — today's `SimpleCompressor` only trims old
+  messages, it doesn't ask the model to summarize them.
+- Hook-triggered HITL pauses — only a tool's own execution body can raise a
+  pause today; a `ToolHook.before_call` cannot.
+- Inline skill-script execution sharing the Bash engine.
+- Rust's `{key}`-style prompt templating.

tokenloop-0.1.3/README.md

@@ -0,0 +1,173 @@
+# ⚡ tokenloop
+
+[![PyPI](https://img.shields.io/pypi/v/tokenloop)](https://pypi.org/project/tokenloop/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/tokenloop/)
+
+A protocol-driven, model-agnostic agent loop for Python. `AgentLoop` runs
+the prompt → model → tool-call → model loop for you — streaming, retries,
+human-in-the-loop pauses, history compaction, and session persistence
+included — while every swappable piece (provider, tool, guardrail, approver,
+compressor, session store) is a plain `typing.Protocol`, not a base class
+you're forced to inherit from.
+
+`tokenloop` is also an active, ongoing **parity port of a companion Rust
+crate** — much of the module layout is deliberately file-for-file with its
+Rust counterpart (`core/loop.py` ↔ `agent/agent.rs`, `core/stream.py` ↔
+`agent/stream.rs`, `core/registry.py` ↔ `run/registry.rs`, and so on), which
+is why you'll find "Python counterpart of ..." in a lot of the source
+docstrings. A few Rust features are deliberately **not** ported yet — see
+[Deliberately not ported](#deliberately-not-ported-yet) below.
+
+## Philosophy
+
+- **Protocol-driven, not inheritance-driven.** `LLMProvider`, `Tool`,
+  `Guardrail`, `Approver`, `Compressor`, `SessionService`, `ToolHook` — every
+  one of these is a structural `Protocol`. Anything with the right shape
+  works; you never subclass a framework base class to plug something in.
+- **`AgentLoop` is stateless; `Session` isn't.** Build one `AgentLoop`, reuse
+  it for every conversation and every concurrent run. All per-conversation
+  state — history, app/user/tmp state, past runs — lives in a `Session`,
+  loaded and saved through a `SessionService` keyed by `session_id`. Nothing
+  conversational is ever held on the `AgentLoop` object itself.
+- **Two different lifetimes, two different objects.** `RunContext` is the
+  *live* object threaded through hooks and tools during one `run()`/
+  `astream()` call — it's never persisted. `RunRecord` is what actually gets
+  written to `Session.runs` once a run finishes: an immutable summary, not a
+  working object.
+- **Every event tells you who and when.** All 20+ event types share one
+  `BaseEvent` (`run_id`, `session_id`, `agent_id`, `created_at`) — full run
+  lifecycle (`RunStarted`/`RunPaused`/`RunError`/`RunCompleted`), per-turn
+  model events, and per-tool-call events, all correlatable.
+
+## Features
+
+- **Core loop** — `AgentLoop` runs a real, working turn loop
+  (`astream()`; `run()` just drains it and returns the final message):
+  automatic retry with exponential backoff on 408/409/429/5xx, best-effort
+  history compaction, a `RunControlService` for pausing/resuming/cancelling
+  a run by `run_id`, and a working interactive CLI (`agent.as_cli()`) for
+  local dev/testing.
+- **Providers** — `LLMProvider` is a `Protocol`; ships with working
+  `AnthropicProvider` and `OpenAIProvider` implementations, both lazily
+  imported so you only pay for the SDK you actually use.
+- **Tools** — `FunctionTool` builds a JSON Schema straight from a plain
+  Python function's signature (stdlib `inspect`/`typing` reflection, no
+  Pydantic). Tool calls in one turn dispatch concurrently. Ships with four
+  builtin tools: `update_state`, `BashTool`, `Read`, and `FileStore`.
+- **Human-in-the-Loop** — a tool can pause a run for `Confirmation`,
+  `InputRequired`, or `ExternalExecution`; an `Approver` can `ALLOW`/`DENY`/
+  `AUDIT` any tool call; `RunMode.INTERACTIVE` vs `NON_INTERACTIVE` controls
+  whether pausing is even allowed; full resume support built in.
+- **Image input** — attach `ImageBase64`/`ImageUrl` sources to a user turn
+  (`image_from_file()` reads and encodes a local file); both providers
+  serialize them into their own content-block format, and context
+  compaction accounts for their token cost.
+- **Guardrails** — `pre_hooks` validate the user's message *before* the
+  model is ever called; `post_hooks` validate the assistant's response.
+  Both also get a fire-and-forget `on_completion` for logging/eval that
+  never adds latency to the run.
+- **Compression** — `SimpleCompressor` trims oldest messages under a token
+  budget (tool-call/result pairing preserved); `HistoryWindow` separately
+  caps the *persisted* session history by message or run count.
+- **Skills** — disk-based, compatible with Anthropic's Agent Skills layout
+  (a `SKILL.md` per skill); every discovered skill resolves into a single
+  `invoke_skill` meta-tool rather than one tool per skill.
+- **MCP** — a client-side bridge (`MCPToolProvider`/`MCPManager`) adapts any
+  MCP server's tools onto the same `Tool` protocol as everything else.
+- **Sessions** — `SessionService` protocol, with an `InMemorySessionService`
+  included (single-process — bring your own for multi-replica deployments).
+- **State** — a standalone `State` utility with delta tracking and an RFC
+  6902 JSON-Patch `diff()`, for building your own state-sync pipeline
+  (not wired into `RunContext`/the AG-UI bridge, which stay plain dicts and
+  full-snapshot-only today).
+- **Streaming & observability** — every run emits a typed `LoopEvent`
+  stream; an `AGUIBridge` translates it into AG-UI protocol events for
+  frontend consumption, and a zero-dependency `SpanCollector` turns it into
+  spans for whatever tracing backend you want to export to.
+
+## Installation
+
+```bash
+pip install tokenloop
+```
+
+`ag-ui-protocol`, `anthropic`, `mcp`, and `openai` are currently all
+unconditional dependencies — one install gets you both providers and the
+AG-UI/MCP protocol surface. (No optional extras exist yet.)
+
+## Quickstart
+
+```python
+import asyncio
+import os
+
+from tokenloop import AgentLoop
+from tokenloop.provider.anthropic import AnthropicProvider
+
+
+async def main() -> None:
+    agent = AgentLoop(
+        AnthropicProvider(model=os.environ["ANTHROPIC_MODEL"]),
+        instruction="You are a concise, helpful assistant.",
+    )
+
+    # Interactive REPL, good for trying things out:
+    await agent.as_cli(None)
+
+    # Or drive it programmatically:
+    # message = await agent.run("session-1", "run-1", "What's 2 + 2?")
+    # print(message.content)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Adding a tool is just a plain Python function:
+
+```python
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    ...
+
+agent.add_tool(get_weather)
+```
+
+See `examples/` for more — tool calling, session state, streaming events,
+and a skills-based agent.
+
+## Testing
+
+```bash
+uv run pytest -v      # 35 passed, 0 failed, 0 skipped
+uv run ruff check     # all checks pass
+uv run python examples/smoke_test.py   # offline, no API key needed
+```
+
+The test suite covers HITL resume (all three pause kinds), a HITL-skipped
+tool not aborting the rest of its batch, `RunControlService`
+(pause/resume/cancel), image serialization for both providers, and
+`State`'s delta-tracking/diff behavior. `examples/smoke_test.py` exercises
+the tool-call round trip and a blocking guardrail end-to-end against a fake
+provider — no network or API key required.
+
+## Documentation
+
+There's no separate docs site yet — this README is it, plus:
+
+- [`docs/HITL_PARITY.md`](docs/HITL_PARITY.md) — a deep dive into the
+  HITL/`RunControlService` design and its parity with the Rust crate.
+- [Repository](https://github.com/RahulDas-dev/loop)
+- [Releases](https://github.com/RahulDas-dev/loop/releases)
+
+## Deliberately not ported (yet)
+
+A few things the companion Rust crate has that this port doesn't, by
+explicit scope decision (see the relevant source docstrings):
+
+- LLM-summarizing compaction — today's `SimpleCompressor` only trims old
+  messages, it doesn't ask the model to summarize them.
+- Hook-triggered HITL pauses — only a tool's own execution body can raise a
+  pause today; a `ToolHook.before_call` cannot.
+- Inline skill-script execution sharing the Bash engine.
+- Rust's `{key}`-style prompt templating.

{tokenloop-0.1.2 → tokenloop-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tokenloop"
-version = "0.1.2"
+version = "0.1.3"
 description = "Add your description here"
 readme = "README.md"
 authors = [
@@ -70,6 +70,7 @@ ignore = [
     "PLR0912",
     "PLR0913",
     "PLR0915",
+    "PLR0917",
     "TRY003",
 ]
 fixable = ["ALL"]

tokenloop-0.1.3/tests/test_images.py

@@ -0,0 +1,90 @@
+"""Tests for image input support - mirrors the portable subset of the Rust
+crate's coverage (schemas/messages.rs, provider/anthropic_runtime.rs,
+provider/openai_runtime.rs, agent/compact.rs). Bedrock and wire_protocol have
+no Python counterpart (no Bedrock provider exists; Python's providers build
+wire payloads inline rather than through a separate reusable module), so
+those 4 Rust tests have no port target here."""
+
+from __future__ import annotations
+
+from tokenloop.core.compact import _estimate_tokens
+from tokenloop.core.types import ImageBase64, ImageUrl, MediaType, Message, image_from_file
+from tokenloop.provider.anthropic import _to_anthropic_messages
+from tokenloop.provider.openai import _to_openai_messages
+
+
+def test_image_from_file_sniffs_known_extensions(tmp_path) -> None:
+    png_path = tmp_path / "test_image.png"
+    png_path.write_bytes(bytes([0, 1, 2, 3]))
+    png = image_from_file(png_path)
+    assert png.media_type == MediaType.PNG
+
+    jpg_path = tmp_path / "test_image.jpg"
+    jpg_path.write_bytes(bytes([4, 5, 6]))
+    jpg = image_from_file(jpg_path)
+    assert jpg.media_type == MediaType.JPEG
+
+
+def test_image_from_file_rejects_unknown_extension(tmp_path) -> None:
+    path = tmp_path / "test_image.bmp"
+    path.write_bytes(bytes([0]))
+    try:
+        image_from_file(path)
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("expected ValueError for an unrecognized extension")
+
+
+def test_anthropic_convert_puts_images_before_trailing_text() -> None:
+    msg = Message(role="user", content="What's this?", images=[ImageBase64(media_type=MediaType.PNG, data="AAAA")])
+    _system, out = _to_anthropic_messages([msg])
+    assert len(out) == 1
+    content = out[0]["content"]
+    assert isinstance(content, list)
+    assert len(content) == 2
+    assert content[0]["type"] == "image"
+    assert content[0]["source"]["type"] == "base64"
+    assert content[0]["source"]["media_type"] == "image/png"
+    assert content[0]["source"]["data"] == "AAAA"
+    assert content[1] == {"type": "text", "text": "What's this?"}
+
+
+def test_anthropic_convert_stays_a_bare_string_without_images() -> None:
+    msg = Message(role="user", content="hello")
+    _system, out = _to_anthropic_messages([msg])
+    assert out[0]["content"] == "hello"
+
+
+def test_openai_convert_builds_content_array_with_data_url() -> None:
+    msg = Message(role="user", content="What's this?", images=[ImageBase64(media_type=MediaType.PNG, data="AAAA")])
+    out = _to_openai_messages([msg])
+    parts = out[0]["content"]
+    assert isinstance(parts, list)
+    assert len(parts) == 2
+    assert parts[0] == {"type": "text", "text": "What's this?"}
+    assert parts[1]["type"] == "image_url"
+    assert parts[1]["image_url"]["url"] == "data:image/png;base64,AAAA"
+
+
+def test_openai_convert_stays_plain_text_without_images() -> None:
+    msg = Message(role="user", content="hello")
+    out = _to_openai_messages([msg])
+    assert out[0]["content"] == "hello"
+
+
+def test_openai_convert_handles_url_sourced_images() -> None:
+    msg = Message(role="user", content=None, images=[ImageUrl(url="https://example.com/cat.png")])
+    out = _to_openai_messages([msg])
+    parts = out[0]["content"]
+    assert parts == [{"type": "image_url", "image_url": {"url": "https://example.com/cat.png"}}]
+
+
+def test_estimate_tokens_accounts_for_images() -> None:
+    plain = [Message(role="user", content="x" * 100)]
+    with_one_image = [Message(role="user", content="x" * 100, images=[ImageBase64(MediaType.PNG, "AAAA")])]
+    two_images = [ImageBase64(MediaType.PNG, "AAAA"), ImageBase64(MediaType.PNG, "BBBB")]
+    with_two_images = [Message(role="user", content="", images=two_images)]
+
+    assert _estimate_tokens(with_one_image) == _estimate_tokens(plain) + 1500
+    assert _estimate_tokens(with_two_images) == 2 * 1500

tokenloop-0.1.3/tests/test_state.py

@@ -0,0 +1,58 @@
+"""Direct translations of the Rust crate's state/types.rs test module."""
+
+from __future__ import annotations
+
+from tokenloop.state import State
+
+
+def test_roundtrip() -> None:
+    state = State()
+    state.set("name", "Alice")
+    assert state.get("name") == "Alice"
+
+
+def test_delta_tracking() -> None:
+    state = State()
+    assert not state.has_delta()
+    state.set("x", 1)
+    assert state.has_delta()
+    d = state.commit()
+    assert d.get("x") == 1
+    assert not state.has_delta()
+    assert state.get("x") == 1
+
+
+def test_remove_records_tombstone() -> None:
+    state = State.from_map({"a": 1})
+    state.remove("a")
+    assert state.get("a") is None
+    assert state.delta().get("a") is None
+    assert "a" in state.delta()
+
+
+def test_from_map_no_initial_delta() -> None:
+    state = State.from_map({"x": 1})
+    assert not state.has_delta()
+
+
+def test_diff_escapes_json_pointer_keys() -> None:
+    state = State.from_map({"a/b~c": 1})
+    patch = state.diff({})
+    assert patch == [{"op": "add", "path": "/a~1b~0c", "value": 1}]
+
+
+def test_diff_is_deterministic() -> None:
+    state = State.from_map({"z": 1, "a": 2})
+    assert state.diff({}) == [
+        {"op": "add", "path": "/a", "value": 2},
+        {"op": "add", "path": "/z", "value": 1},
+    ]
+
+
+def test_diff_reports_replace_and_remove() -> None:
+    state = State.from_map({"a": 1})
+    state.set("a", 2)
+    assert state.diff({"a": 1, "b": 9}) == [
+        {"op": "replace", "path": "/a", "value": 2},
+        {"op": "remove", "path": "/b"},
+    ]

{tokenloop-0.1.2 → tokenloop-0.1.3}/tokenloop/__init__.py

@@ -49,6 +49,10 @@ from tokenloop.core.registry import RunControlService
 from tokenloop.core.types import (
     CompletionResult,
     GenerationParams,
+    ImageBase64,
+    ImageSource,
+    ImageUrl,
+    MediaType,
     Message,
     Role,
     ToolCall,
@@ -56,6 +60,7 @@ from tokenloop.core.types import (
     ToolResult,
     ToolSpec,
     Usage,
+    image_from_file,
 )
 from tokenloop.guardrails.base import Guardrail, GuardrailViolationError
 from tokenloop.hitl.base import (
@@ -78,6 +83,7 @@ from tokenloop.session_service.base import RunRecord, Session, SessionService
 from tokenloop.session_service.memory import InMemorySessionService
 from tokenloop.skills.base import LocalSkillLoader, Skill, SkillLoader
 from tokenloop.skills.manager import INVOKE_SKILL_TOOL_NAME, SkillManager
+from tokenloop.state import State
 from tokenloop.tool.base import FunctionTool, Tool
 from tokenloop.tool.builtins.bash_tool import BASH_TOOL_NAME
 from tokenloop.tool.builtins.read_tool import READ_TOOL_NAME
@@ -116,6 +122,9 @@ __all__ = [
     "HitlResume",
     "HitlSignal",
     "HitlSkipped",
+    "ImageBase64",
+    "ImageSource",
+    "ImageUrl",
     "InMemorySessionService",
     "InputField",
     "InputRequired",
@@ -125,6 +134,7 @@ __all__ = [
     "MCPManager",
     "MCPTool",
     "MCPToolProvider",
+    "MediaType",
     "Message",
     "MessageEnd",
     "MessageStart",
@@ -153,6 +163,7 @@ __all__ = [
     "SkillInvoked",
     "SkillLoader",
     "SkillManager",
+    "State",
     "TextDelta",
     "Tool",
     "ToolCall",
@@ -166,4 +177,5 @@ __all__ = [
     "ToolResult",
     "ToolSpec",
     "Usage",
+    "image_from_file",
 ]

{tokenloop-0.1.2 → tokenloop-0.1.3}/tokenloop/core/cli.py

@@ -185,7 +185,7 @@ async def _run_one_stream(
     pending_resume: HitlResume | None = None
 
     try:
-        async for event in agent.astream(session_id, run_id, user_msg, opts):
+        async for event in agent.astream(session_id, run_id, user_msg, run_options=opts):
             if isinstance(event, TextDelta):
                 if not text_open:
                     print(f"{_ts()}   {_C_TEXT}Assistant:{_RST} ", end="", flush=True)

{tokenloop-0.1.2 → tokenloop-0.1.3}/tokenloop/core/compact.py

@@ -16,10 +16,17 @@ if TYPE_CHECKING:
 
 _CHARS_PER_TOKEN = 4  # crude estimate, matches compression/simple.py's own heuristic
 _MAX_COMPACTION_FAILURES = 3
+# A crude, deliberately conservative flat estimate - real per-image cost
+# depends on resolution and provider, but ignoring images entirely would
+# make autocompaction fire too late once they start consuming real context
+# budget. Matches the Rust crate's agent/compact.rs::ESTIMATED_TOKENS_PER_IMAGE.
+_ESTIMATED_TOKENS_PER_IMAGE = 1500
 
 
 def _estimate_tokens(messages: list[Message]) -> int:
-    return sum(len(m.content or "") for m in messages) // _CHARS_PER_TOKEN
+    text_tokens = sum(len(m.content or "") for m in messages) // _CHARS_PER_TOKEN
+    image_tokens = sum(len(m.images) for m in messages) * _ESTIMATED_TOKENS_PER_IMAGE
+    return text_tokens + image_tokens
 
 
 async def maybe_compact(

{tokenloop-0.1.2 → tokenloop-0.1.3}/tokenloop/core/loop.py

@@ -34,7 +34,7 @@ if TYPE_CHECKING:
     from tokenloop.core.context import RunContext, RunOptions
     from tokenloop.core.events import LoopEvent
     from tokenloop.core.registry import RunControlService
-    from tokenloop.core.types import Message
+    from tokenloop.core.types import ImageSource, Message
     from tokenloop.guardrails.base import Guardrail
     from tokenloop.hitl.base import Approver
     from tokenloop.provider.base import LLMProvider
@@ -140,22 +140,24 @@ class AgentLoop:
         session_id: str,
         run_id: str,
         user_msg: str,
+        images: list[ImageSource] | None = None,
         run_options: RunOptions | None = None,
         *,
         user_id: str | None = None,
     ) -> Message:
-        return await core_run.run(self, session_id, run_id, user_msg, run_options, user_id=user_id)
+        return await core_run.run(self, session_id, run_id, user_msg, images, run_options, user_id=user_id)
 
     def astream(
         self,
         session_id: str,
         run_id: str,
         user_msg: str,
+        images: list[ImageSource] | None = None,
         run_options: RunOptions | None = None,
         *,
         user_id: str | None = None,
     ) -> AsyncIterator[LoopEvent]:
-        return core_stream.astream(self, session_id, run_id, user_msg, run_options, user_id=user_id)
+        return core_stream.astream(self, session_id, run_id, user_msg, images, run_options, user_id=user_id)
 
     async def as_cli(self, session_id: str | None = None) -> None:
         await core_cli.as_cli(self, session_id)

{tokenloop-0.1.2 → tokenloop-0.1.3}/tokenloop/core/run.py

@@ -17,6 +17,7 @@ from tokenloop.core.types import Message
 if TYPE_CHECKING:
     from tokenloop.core.context import RunOptions
     from tokenloop.core.loop import AgentLoop
+    from tokenloop.core.types import ImageSource
 
 
 async def run(
@@ -24,11 +25,12 @@ async def run(
     session_id: str,
     run_id: str,
     user_msg: str,
+    images: list[ImageSource] | None = None,
     run_options: RunOptions | None = None,
     *,
     user_id: str | None = None,
 ) -> Message:
-    async for event in astream(agent, session_id, run_id, user_msg, run_options, user_id=user_id):
+    async for event in astream(agent, session_id, run_id, user_msg, images, run_options, user_id=user_id):
         if isinstance(event, RunCompleted):
             # RunResult.tool_calls accumulates every call made across the
             # whole run (for callers inspecting the run's history) - the