tokenloop 0.1.0__tar.gz → 0.1.2__tar.gz

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

@@ -8,3 +8,9 @@ wheels/
 
 # Virtual environments
 .venv
+
+# Local secrets / editor tooling
+.env
+.claude/
+.ruff_cache/
+.pytest_cache/

tokenloop-0.1.2/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agno-docs": {
+      "type": "http",
+      "url": "https://docs.agno.com/mcp"
+    }
+  }
+}

tokenloop-0.1.2/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.5
+Name: tokenloop
+Version: 0.1.2
+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
+
+> A lightweight, modular, model-agnostic agent loop and token-streaming framework designed for maximum performance and zero bloat.
+
+## Features
+
+*   **Modular Execution Loop**  
+    A clean, unopinionated event loop built on the Unix philosophy. Step through prompts, model inferences, and tool executions predictably without heavy state abstractions.
+
+*   **Model-Agnostic Provider Support**  
+    Bring your own provider. Seamlessly switch between local models, cloud APIs, or custom backends with zero code refactoring.
+
+*   **Skills Support**
+    Add Local Skills with Validation tokenloops responsibilty    
+
+*   **First-Class Tool Calling**  
+    Effortlessly register native functions or structured Python/Rust/Go methods as executable agent tools with automatic schema generation.
+
+*   **Model Context Protocol (MCP) Integration**  
+    Out-of-the-box client support for MCP servers, allowing your agents to dynamically discover and consume external resources and tools.
+
+*   **Human-in-the-Loop (HITL) Checkpoints**  
+    Inject asynchronous approval hooks before executing critical or sensitive tool calls, ensuring absolute safety and human oversight.
+
+*   **Intelligent Context Compression**  
+    Built-in utilities to prune, summarize, and compress long conversation histories to keep token windows tight and latency low.
+
+*   **AGUI & Real-Time Token Streaming**  
+    First-class support for streaming tokens and structured UI events simultaneously, powering responsive agent-driven user interfaces.
+
+*   **Multi-Language Ergonomics**  
+    Consistent, idiomatic APIs available natively across Python, Rust, Go, and Node.js.
+
+*   **Zero Bloat Architecture**  
+    Extremely lightweight core footprint with zero unnecessary dependencies, giving you total control over performance.

tokenloop-0.1.2/README.md

@@ -0,0 +1,35 @@
+# ⚡ tokenloop
+
+> A lightweight, modular, model-agnostic agent loop and token-streaming framework designed for maximum performance and zero bloat.
+
+## Features
+
+*   **Modular Execution Loop**  
+    A clean, unopinionated event loop built on the Unix philosophy. Step through prompts, model inferences, and tool executions predictably without heavy state abstractions.
+
+*   **Model-Agnostic Provider Support**  
+    Bring your own provider. Seamlessly switch between local models, cloud APIs, or custom backends with zero code refactoring.
+
+*   **Skills Support**
+    Add Local Skills with Validation tokenloops responsibilty    
+
+*   **First-Class Tool Calling**  
+    Effortlessly register native functions or structured Python/Rust/Go methods as executable agent tools with automatic schema generation.
+
+*   **Model Context Protocol (MCP) Integration**  
+    Out-of-the-box client support for MCP servers, allowing your agents to dynamically discover and consume external resources and tools.
+
+*   **Human-in-the-Loop (HITL) Checkpoints**  
+    Inject asynchronous approval hooks before executing critical or sensitive tool calls, ensuring absolute safety and human oversight.
+
+*   **Intelligent Context Compression**  
+    Built-in utilities to prune, summarize, and compress long conversation histories to keep token windows tight and latency low.
+
+*   **AGUI & Real-Time Token Streaming**  
+    First-class support for streaming tokens and structured UI events simultaneously, powering responsive agent-driven user interfaces.
+
+*   **Multi-Language Ergonomics**  
+    Consistent, idiomatic APIs available natively across Python, Rust, Go, and Node.js.
+
+*   **Zero Bloat Architecture**  
+    Extremely lightweight core footprint with zero unnecessary dependencies, giving you total control over performance.

tokenloop-0.1.2/docs/HITL_PARITY.md

@@ -0,0 +1,303 @@
+# Python HITL / RunControl parity gap analysis
+
+This document originally recorded an **analysis only**, with nothing yet
+implemented. **All 8 gaps below, plus the follow-up findings section, have
+since been implemented** (see "Implementation notes" at the end of this
+file). It's kept as-is otherwise, as the design record of why each change
+was made and what it mirrors in the Rust crate (`rust/tokenloop`) for
+**HITL and `RunControlService`** specifically. Image input support remains a
+separate, out-of-scope divergence not covered here.
+
+Scope basis: over two rounds of work, the Rust side (1) unified
+Confirmation/InputRequired/ExternalExecution onto a single non-blocking pause
+mechanism, then (2) added `RunMode`/`HitlSkipped` (NonInteractive mode), a
+`result` field on `HitlResume`, an `"ext_pending"`/`"hitl_pending"` key split,
+and restored `RunControlService` (manual pause/cancel from a UI button — not
+itself a HITL-detection mechanism, but included here per explicit request).
+Python was ported from an earlier snapshot, before any of round (2) existed,
+and has not been touched since.
+
+## Already correct — no change needed
+
+- **The core pause contract already matches Rust's target design.** Both
+  Python trigger paths — `HitlSignal` raised from a tool/hook
+  (`tool/registry.py:44-50` → `core/dispatch.py:114-123`) and
+  external-execution detection (`core/dispatch.py:150-169`) — write a pending
+  entry into `ctx.tmp_state` and return/break immediately. No channel, no
+  future, no blocking wait. This is exactly what the Rust side had to be
+  *corrected to* (its `ExternalExecution` path used to block via
+  `RunControlService` before this session's unification work) — Python
+  already had it right from the start.
+- **`ToolHooks.before_call(call: ToolCall, run_context)` already receives the
+  real `tool_call_id`** via `call.id` (`tool/hooks.py:14-15`, `core/types.py:8-11`).
+  Rust's equivalent, `before_call(name: &str, args: Value, ctx: SharedContext)`
+  (`src/tool/hooks.rs`), does **not** get the id — a documented Rust gotcha
+  that forces its hooks to mint their own `uuid::Uuid::new_v4()`. Python is
+  strictly better here; do not regress this when porting anything below.
+- **Python has a single turn-loop implementation.** `core/stream.py`'s
+  `_run_turns`/`astream` contains all turn-loop logic; `core/run.py::run` is
+  a thin wrapper that drains `astream()` (`core/run.py:1-45`). Every change
+  below applies in **one place**, unlike Rust's independently hand-duplicated
+  `src/agent/run.rs` / `src/agent/stream.rs`.
+
+## Gap 1 — `hitl/base.py`: shape drift vs. `src/schemas/hitl.rs`
+
+| Type | Python today | Rust (`src/schemas/hitl.rs`) | Gap |
+|---|---|---|---|
+| `InputField` | doesn't exist | `struct InputField { name, description, options: Option<Vec<String>>, value: Option<Value> }` (lines 6-13) | Add the struct; `InputRequired.fields` needs it. |
+| `InputRequired.fields` | `list[str]` (line ~35) | `Vec<InputField>` (line 19) | Unstructured — should hold real `InputField` entries. |
+| `Confirmation.fields` | `list[str]` (line ~44) | `Vec<(String, String)>` (line 30) | Should be label/value pairs, e.g. `list[tuple[str, str]]`. |
+| `Confirmation.title` | `str` (required) | `Option<String>` with `#[serde(default)]` (line 28) | Should be optional. |
+| `ExternalExecution` | `tool_call_id, tool_name` | same | Matches exactly — no change. |
+| `HitlPending` | `tool_call_id, tool_name, arguments` (lines 54-58) | `tool_call_id, tool_name, args, kind` (lines 47-53) | **Missing `kind` entirely.** Python's dispatch functions return kind out-of-band (`([], paused_kind, paused_correlation_id)`) instead of persisting it — pending state isn't self-describing from session storage alone the way Rust's is. |
+| `HitlResume` | `tool_call_id, approved, note` (lines 60-63) | `tool_call_id, approved, note, fields, result` (lines 61-74) | **Missing `fields` and `result`.** Today `InputRequired` answers are JSON-stuffed into `note` as a workaround (`core/cli.py:137-142`, `_prompt_input_required`). |
+
+## Gap 2 — `core/dispatch.py`: kind on write, and `HitlSkipped` handling
+
+Both write sites need `kind=` added once `HitlPending` gains the field:
+- Hook-triggered path, `core/dispatch.py:230-258`.
+- External-execution path, `core/dispatch.py:150-169`.
+
+Rust's `dispatch.rs` (lines 34-73) has a third case Python has no equivalent
+for: a hook can return `Err(AgentError::HitlSkipped(msg))` instead of pausing,
+used for NonInteractive mode (see Gap 3). Rust handles this with a `skipped`
+accumulator — the affected call gets a synthetic error result and the *rest
+of the batch still dispatches normally* (unlike a real pause, which stops
+everything). Porting this requires the per-call loop in `core/dispatch.py`
+(currently around `_execute_tracked`, lines 114-123) to distinguish two
+exception types instead of one:
+- `HitlSignal` → stop the whole batch (today's only behavior, unchanged).
+- `HitlSkipped` (new) → give just that call a synthetic error `ToolResult`,
+  continue dispatching every other call in the batch.
+
+## Gap 3 — `core/context.py`: `RunMode` / `HitlSkipped` are entirely absent
+
+Confirmed via full-package grep: no `RunMode`, `run_mode`, or `HitlSkipped`
+exists anywhere in Python today. Rust's shape (`src/run/options.rs`,
+`src/run/context.rs`, `src/error.rs`):
+
+```rust
+pub enum RunMode { Interactive, NonInteractive } // Copy, Default = Interactive, Serialize/Deserialize
+// RunOptions.run_mode: RunMode
+// RunContext.run_mode() -> RunMode
+// AgentError::HitlSkipped(String)
+```
+
+Needed: a `RunMode` enum (`INTERACTIVE`/`NON_INTERACTIVE`, default
+`INTERACTIVE`), `RunOptions.run_mode`, `RunContext.run_mode` (copied from
+options at context construction — mirrors how `setup_run_context` feeds it
+in Rust, `src/agent/shared.rs`), and a `HitlSkipped` exception type
+alongside the existing `HitlSignal` (`hitl/base.py:78-87`). A hook checks
+`run_context.run_mode` *before* deciding to pause, exactly like the Rust
+example in `docs/HITL.md`'s "NonInteractive mode" section.
+
+## Gap 4 — `RunControlService` equivalent: absent by design, now requested
+
+Confirmed via grep: no registry, no `pause`/`resume`/`cancel`/`is_paused`
+methods, no `RunControlService`-named anything exists in Python. What exists
+instead is much thinner and explicitly documented as a deliberate
+simplification (`core/context.py:22-27`, `core/cli.py:6-14`): a single
+caller-owned `asyncio.Event` on `RunOptions.cancel`, checked once per turn
+(`core/stream.py:260-261`). This is functionally equivalent to *half* of
+Rust's `RunControlService` (the cancel flag) but has no run-id-keyed registry
+and no manual pause/resume concept at all.
+
+Rust's `src/run/registry.rs` API to mirror:
+
+```rust
+pub struct RunControlService { runs: Arc<Mutex<HashMap<String, Arc<AtomicBool>>>>, paused_ids: Arc<Mutex<HashSet<String>>> }
+fn register(&self, run_id: &str, cancel_flag: Arc<AtomicBool>)
+fn unregister(&self, run_id: &str)
+fn cancel(&self, run_id: &str) -> bool
+fn cancel_all(&self)
+fn pause(&self, run_id: &str) -> bool
+fn resume(&self, run_id: &str) -> bool
+fn is_paused(&self, run_id: &str) -> bool
+fn active_ids(&self) -> Vec<String>
+```
+
+A Python port (e.g. new `core/registry.py`) would hold `dict[str,
+asyncio.Event]` + `set[str]` with the same method names/semantics. Unlike
+Rust, no `Mutex` equivalent is strictly required if all access happens on one
+event loop (Rust's lock exists because multiple OS threads touch it) — this
+should be called out explicitly in the implementation rather than blindly
+adding a `threading.Lock`. `AgentLoop` would gain an optional
+`run_control_service` parameter (mirrors `AgentBuilder::run_control_service`,
+`src/agent/builder.rs:542-545`).
+
+Wiring needed in `core/stream.py`, the single turn-loop file:
+- Auto-register/-unregister the run's cancel `asyncio.Event` with
+  `run_control_service` when one is wired — mirrors `setup_run_context`
+  (`src/agent/shared.rs:371-376`) and its `finalize_and_save` unregister call.
+- A manual pause spin-wait immediately before the existing cancel check at
+  `core/stream.py:260-261`, mirroring `src/agent/run.rs:274-297`: while
+  `rc.is_paused(run_id)`, sleep 50ms in a loop up to `MAX_PAUSE_ITERS = 36_000`
+  (30 minutes), still honoring cancel while paused, warn+auto-resume on
+  timeout.
+
+## Gap 5 — `core/shared.py`: `inject_hitl_resume` must become kind-aware
+
+Today (`core/shared.py:37-57`) resume-text computation is a single
+unconditional formula applied to every kind:
+`resume.note or "Approved."` if approved, else
+`f"Rejected: {resume.note or 'No reason given.'}"`.
+
+This is correct for `Confirmation` but **wrong for `ExternalExecution`** —
+Rust never wraps an `ExternalExecution` result in approve/reject phrasing;
+it just uses `result`, falling back to `note`, falling back to `"OK"` (see
+`docs/HITL.md`'s resume table, sourced from `inject_hitl_resume`'s match in
+`src/agent/shared.rs`). Once `HitlPending.kind` exists (Gap 1), Python should
+branch:
+
+| `HitlKind` | Fields read | Resulting tool_result text |
+|---|---|---|
+| `Confirmation` | `approved`, `note` | `note` (or `"Approved."`) if approved; `"Rejected: {note}"` (or `"No reason given."`) if not — **unchanged from today** |
+| `InputRequired` | `fields` | the filled `InputField`s serialized as a JSON object — today done via `note`-stuffing in `core/cli.py`, should move to a real `fields` value |
+| `ExternalExecution` | `result`, falls back to `note`, falls back to `"OK"` | **new** — today incorrectly gets Confirmation-style approve/reject phrasing |
+
+**Deliberate non-port, worth recording so it isn't "rediscovered" as a missing
+gap later:** Rust splits `"hitl_pending"` (hook-triggered) from
+`"ext_pending"` (external-execution) as two separate `temp_state` keys,
+purely because two independent write sites needed to stay distinguishable
+downstream. Once Python's `HitlPending` always carries `kind` (Gap 1), a
+single `"hitl_pending"` key is already self-describing — a second key would
+be redundant complexity that Rust needs and Python doesn't. **Recommendation:
+keep Python's single-key design.**
+
+## Gap 6 — `core/cli.py`: update `HitlResume(...)` construction sites
+
+Once `fields`/`result` exist (Gap 1), `core/cli.py`'s `_prompt_input_required`
+(lines 137-142) should pass filled `InputField`s via `fields=` instead of
+JSON-encoding them into `note`, and any `ExternalExecution` resume site should
+use `result=` instead of `note=`/`approved=`.
+
+## Gap 7 — Test coverage to add
+
+Mirror Rust's coverage as a checklist for whoever implements this:
+- `src/agent/shared.rs`'s ~8 tests: one per kind's resume-text logic
+  (Confirmation approved/rejected, InputRequired fields-as-JSON,
+  ExternalExecution result-wins-over-note, falls-back-to-note,
+  falls-back-to-"OK").
+- `src/run/registry.rs`'s 7 tests: pause/resume round-trip, pause on unknown
+  run_id is a no-op, cancel sets the flag, cancel on unknown run_id returns
+  false, cancel_all sets every flag, register/unregister lifecycle.
+- A `HitlSkipped`-in-NonInteractive-mode test: the skipped call gets a
+  synthetic error result, every other call in the same batch still dispatches.
+
+## Summary of files that would need changes (not made in this task)
+
+- `hitl/base.py` — `InputField`, richer `Confirmation`/`InputRequired.fields`,
+  `HitlPending.kind`, `HitlResume.fields`/`.result`.
+- `core/dispatch.py` — `kind=` on both `HitlPending` writes; `HitlSkipped`
+  handling in the per-call dispatch loop.
+- `core/context.py` — `RunMode` enum, `RunOptions.run_mode`,
+  `RunContext.run_mode`.
+- new `core/registry.py` — `RunControlService` port.
+- `core/stream.py` — register/unregister with `run_control_service`; pause
+  spin-wait before the existing cancel check.
+- `core/shared.py` — kind-aware `inject_hitl_resume`; keep the single
+  `"hitl_pending"` key (documented non-port of Rust's key split).
+- `core/cli.py` — update `HitlResume(...)` call sites to use `fields`/`result`.
+
+## Update — findings from Rust's RunPaused/HitlSkipped event-lifecycle fixes
+
+The Rust crate's `docs/syncup.md` was later updated with 5 more gaps (all
+confirmed and fixed this session, in `src/agent/stream.rs` and
+`src/agent/run.rs`): `RunPaused` wasn't emitted for hook-triggered HITL
+during streaming (2 sites), `HitlSkipped` didn't emit a matching
+`PreHookCompleted` and incorrectly ran `after_call` (2 sites), and a
+`finish_reason=ToolCalls`-with-no-tool-calls anomaly went unlogged (1 site).
+Each was checked directly against the current Python source below - most
+don't apply the way they did in Rust, but two new structural findings
+surfaced that matter more than the original gaps.
+
+**Gaps 1+2 (`RunPaused` not emitted for hook-triggered HITL) — N/A, Python
+already correct.** `core/dispatch.py`'s single `dispatch_tools` (Python has
+one dispatch function/turn loop, unlike Rust's early-dispatch vs.
+assembled-dispatch split in `stream.rs`) already emits `RunPaused` at both
+pause sites: external-execution (`dispatch.py:159-168`) and the
+tool-body-raised `HitlSignal` path (`dispatch.py:240-249`). Python never had
+this gap.
+
+**New finding — Python's pause-triggering surface is narrower than Rust's.**
+Rust's `examples/hitl.rs` pauses from `ToolHooks::before_call` (the
+`ApprovalHook` pattern - a hook decides to pause). Python's `HitlSignal` is
+designed to be raised only from inside a tool's own execution body
+(`hitl/base.py:78-87`'s docstring: "Raise this from inside a tool's own
+body"). `dispatch.py`'s `_run_before_call_hooks` (lines 64-85) has **no
+`try/except HitlSignal`** around its `hook.before_call(current, ctx)` call,
+unlike `_execute_tracked` (lines 114-123), which does wrap tool execution in
+exactly that way. If a hook raised `HitlSignal` today the way Rust's
+`ApprovalHook` does, it would propagate **uncaught** out of `dispatch_tools`
+instead of pausing cleanly - there is no example or test exercising this, so
+it's untested territory. This is an open design question, not yet a filed
+gap: either (a) document explicitly that Python hooks may only rewrite
+args and never request a pause - only tool bodies can - or (b) extend
+`_run_before_call_hooks` to catch `HitlSignal` (and, later, `HitlSkipped`)
+the same way tool execution is wrapped, to match Rust's
+hook-triggered-pause pattern.
+
+**Gaps 3+4 (`HitlSkipped` event-lifecycle correctness) — not yet actionable
+in Python (no `HitlSkipped` exists yet, see Gap 2/3 above), but two concrete
+requirements to carry into that future work:**
+- Whichever code path ends up allowed to raise `HitlSkipped` (per the finding
+  above) must still emit the matching `PreHookCompleted` before propagating -
+  mirroring the Rust fix that added this for its early-dispatch path
+  (`stream.rs`'s early-dispatch `HitlSkipped` arm was missing it).
+- **New structural finding, more significant than the original gap**: Rust's
+  target behavior for a skipped call is "fire `on_complete` only, never
+  `after_call`". Python's `ToolHook` protocol (`tool/hooks.py:7-27`) has
+  `before_call` / `after_call` / `on_completion` - but `on_completion(self,
+  run_context)` fires **once per run** (a background task scheduled after the
+  whole run ends, for logging/eval side effects), not once per tool call,
+  unlike Rust's `ToolHooks::on_complete(name, output, ctx)`, which fires once
+  per call. **Python has no per-call, non-rewriting "always observe" hook
+  stage today.** Before porting `HitlSkipped`, this needs a decision: either
+  add a per-call `on_complete`-equivalent to `ToolHook`, or accept that a
+  skipped call in Python will always flow through `after_call` (Python can't
+  cheaply replicate "skip `after_call` for just this one call" without that
+  addition).
+
+**Gap 5 (silent `finish_reason=ToolCalls` anomaly, `run.rs`) — out of scope,
+and no 1:1 port target exists.** This is a general provider-response
+robustness log, not a HITL/RunControlService concern, so it falls outside
+this comparison's scope. It also has no direct port target: Python's turn
+loop (`core/stream.py:238`, `if not message.tool_calls:`) doesn't track
+`finish_reason` at that level at all - `Message` doesn't carry one. Recording
+this explicitly as "out of scope, no action" so it isn't mistaken for an
+overlooked gap later.
+
+## Implementation notes
+
+All 8 numbered gaps above were implemented, plus the follow-up findings
+section's items 1-3 (item 4/Gap 5 stayed out of scope as recorded). Two
+things came out different from what the analysis above predicted:
+
+- **`core/dispatch.py`'s `HitlSkipped` handling needed zero new code.**
+  Raising `HitlSkipped` from a tool body falls through to
+  `ToolRegistry.execute()`'s existing generic `except Exception` clause,
+  which already produces a per-call `ToolResult(is_error=True)` while
+  `asyncio.gather` keeps every other call in the batch running - exactly the
+  "skip this call, don't stop the batch" behavior NonInteractive mode needs.
+  Unlike Rust's `dispatch.rs` (which needs an explicit `skipped` accumulator
+  because its `before_call` hooks run sequentially, pre-dispatch, for the
+  whole batch), Python's concurrent per-call execution already isolates each
+  call's exception. `hitl/base.py::HitlSkipped` and a doc comment in
+  `tool/registry.py` are the only additions.
+- **The "hooks can't trigger a pause" open design question (from the
+  follow-up findings section) was deliberately left unresolved.** `HitlSkipped`
+  is raised from tool bodies, same as `HitlSignal`, sidestepping the question
+  entirely rather than resolving it - `core/dispatch.py::_run_before_call_hooks`
+  still has no `try/except` around `hook.before_call(...)`. Porting Rust's
+  `examples/hitl.rs`-style hook-triggered Confirmation pause into Python
+  would still require that separate change.
+
+Files touched: `hitl/base.py`, `core/context.py`, `core/dispatch.py`,
+`tool/registry.py`, `core/registry.py` (new), `core/loop.py`,
+`core/stream.py`, `core/shared.py`, `core/cli.py`, `stream/agui.py` (its
+`InputRequired`/`Confirmation` JSON-schema builder needed updating for the
+new `InputField`/tuple-pair shapes - not part of the original 8-item list,
+found by grepping for every `.fields` access after the schema change), plus
+new tests under `tests/` (`pytest` added as a dev dependency - the port had
+no test suite before this). Verified with `ruff check`, `ruff format --check`,
+the new `pytest` suite (20 tests), and `examples/smoke_test.py`.

tokenloop-0.1.2/examples/basic_chat.py

@@ -0,0 +1,36 @@
+"""Basic chat - no tools, multi-turn conversation.
+
+Run:
+    uv run python examples/basic_chat.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from tokenloop import AgentLoop
+from tokenloop.provider.anthropic import AnthropicProvider
+
+try:  # best-effort .env loading, matches Rust's dotenvy::dotenv().ok()
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ImportError:
+    pass
+
+
+async def main() -> None:
+    agent = AgentLoop(
+        AnthropicProvider(model=os.environ.get("ANTHROPIC_MODEL", "claude-sonnet-4-5")),
+        instruction=(
+            "You are a concise, helpful assistant. Keep answers under 3 sentences unless more detail is requested."
+        ),
+        inject_datetime=True,
+    )
+
+    await agent.as_cli(None)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tokenloop-0.1.2/examples/session_state.py

@@ -0,0 +1,68 @@
+"""Session state - app_state, user_state, temp_state.
+
+Demonstrates:
+    - Tools reading and writing state via a `ctx` parameter (see
+      tool/base.py::FunctionTool - naming a parameter exactly `ctx` opts a
+      tool into receiving the live RunContext; it's excluded from the JSON
+      schema the model sees).
+    - State surviving across turns within the same session.
+
+Try: "What is my profile?" then "Change my name to Alice"
+
+Run:
+    uv run python examples/session_state.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from tokenloop import AgentLoop, RunContext
+from tokenloop.provider.anthropic import AnthropicProvider
+
+try:  # best-effort .env loading, matches Rust's dotenvy::dotenv().ok()
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ImportError:
+    pass
+
+
+async def get_profile(ctx: RunContext) -> str:
+    """Return the current user profile from session state."""
+    name = ctx.user_state.get("user_name", "Guest")
+    turns = ctx.user_state.get("turn_count", 0) + 1
+    ctx.user_state["turn_count"] = turns
+    return f'{{"name": "{name}", "turn_count": {turns}}}'
+
+
+async def update_name(name: str, ctx: RunContext) -> str:
+    """Update the user's name in session state."""
+    ctx.user_state["user_name"] = name
+    return f"Name updated to '{name}'"
+
+
+async def main() -> None:
+    agent = AgentLoop(
+        AnthropicProvider(model=os.environ.get("ANTHROPIC_MODEL", "claude-sonnet-4-5")),
+        instruction=(
+            "You are a personalized assistant.\n"
+            "The user's name is stored in session state under 'user_name'.\n"
+            "Call get_profile to read it and update_name to change it."
+        ),
+    )
+    agent.add_tool(get_profile)
+    agent.add_tool(update_name)
+
+    session = await agent._session_service.new(user_id="demo-user", agent_id=agent._id)  # noqa: SLF001
+    session.user_state["user_name"] = "Guest"
+    session.user_state["turn_count"] = 0
+    await agent._session_service.save(session)  # noqa: SLF001
+
+    print(f"Session: {session.session_id}")
+    await agent.as_cli(session.session_id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tokenloop-0.1.2/examples/skills/explain-topic/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: explain-topic
+description: Explains a technical process, system, protocol, or algorithm using a vertical ASCII "activity diagram" - numbered steps, blocking/waiting calls called out explicitly, and decision forks drawn as branches with a merge back to a single flow. Use this whenever the user asks to explain, walk through, or break down how something works, especially when the thing has sequential stages, async/blocking behavior, event emissions, or a conditional branch (approved/rejected, success/failure, cache hit/miss, etc). Trigger on phrases like "explain how X works", "walk me through X", "what happens when X", "trace the flow of X", or "diagram X" - even if the user doesn't explicitly ask for a diagram, if the topic is a multi-step process this is the preferred explanation format. Do not use for purely conceptual/definitional questions with no sequence or steps (e.g. "what is a hash map").
+---
+
+# Explain Topic (ASCII Flow Diagram)
+
+Explain processes as a single vertical control-flow diagram in plain ASCII/text - the same style as a UML activity diagram, but compact and rendered directly in chat (no image, no artifact, no Visualizer tool).
+
+## When to use this
+
+Use this format when the topic has:
+- A **sequence of discrete stages** (setup -> action -> result)
+- Any **blocking or waiting** step (I/O, a lock, a human approval, a network call)
+- A **decision/branch point** (success vs failure, approved vs rejected, hit vs miss)
+- **Events or side effects** fired along the way (logs, emitted events, callbacks)
+
+Skip this format for static/definitional questions ("what is X", "difference between X and Y") that have no real sequence - just answer those in prose.
+
+## Diagram conventions
+
+Follow this exact visual grammar so output stays consistent:
+
+1. **Single vertical spine.** One flow goes top to bottom. Steps stack with `|` / `v` connectors between them:
+   ```text
+   |
+   v
+   ① Step happens
+
+```
+
+2. **Numbered circled steps** using ①②③④⑤⑥⑦⑧⑨⑩ for the main stages. Each step gets:
+* A short label naming the concrete action (use real function/method/event names if known - not generic placeholders)
+* Optional indented detail lines starting with `- `, `->`, or `=` for sub-actions inside that step
+
+
+3. **Explicit blocking steps** get labeled with `<- BLOCKS HERE` or `-> awaits response`, so the reader immediately sees where execution stalls.
+4. **Decision forks** get drawn as an explicit branch, not just described in prose:
+```text
+      |
+ +----+----+
+ |         |
+condition A   condition B
+ |         |
+ v         v
+outcome path 1   outcome path 2
+
+```
+
+
+Each branch should show what happens differently (e.g. one continues the flow, one short-circuits/errors out).
+5. **Merge back to one spine** after a branch, if the branches reconverge later - don't leave two dangling columns if the real process rejoins.
+6. **Use small icons sparingly** for recognizable states, only if they add clarity: `o` running/executing, `=` paused/waiting, `v` success/done, `x` failure/rejected. Don't overuse - one or two per diagram is usually enough.
+7. **Keep labels concrete, not abstract.** Prefer `registry.submit_hitl(id, Confirmed)` over "system processes confirmation". If you don't know the exact real-world name, use a plausible concrete placeholder rather than a vague noun phrase.
+8. **Diagram first, then explain.** Output the diagram, then follow it with a short prose paragraph (3-6 sentences) that: names what pattern this is (if there's a recognizable one - interceptor, producer/consumer, ask pattern, etc.), and calls out the one or two trickiest parts of the flow (usually the blocking step or the branch).
+
+## Worked example
+
+For reference, here's the target shape and density (this is the level of detail to aim for - not longer, not much shorter):
+
+```text
+LLM decides to call bash tool with cmd = "python hitl_transfer.py"
+  |
+  v
+① ToolCallStarted event emitted
+  - CLI prints: o bash id=tc-123
+  |
+  v
+② tool_hooks.before_call("bash", args, ctx) - BLOCKS HERE
+  - detects trigger condition
+  - creates oneshot channel, registers correlation_id
+  - event_tx.send(RunPaused { "Execute hitl_transfer.py?" })
+  - rx.await -> agent task blocks, no more events produced
+
+CLI receives RunPaused -> prints = confirm prompt
+teller responds "y" -> registry.submit_hitl(id, Confirmed)
+  - fires oneshot -> rx.await unblocks
+  |
+  +--------+--------+
+  |                 |
+approved        rejected
+  |                 |
+  v                 v
+③ hook returns Ok    ToolCallError emitted
+  (continue)         -> tool never runs, LLM sees error
+  |
+  v
+④ reg.dispatch_all() -> tool actually executes
+  |
+  v
+⑤ ToolCallCompleted event emitted
+  - CLI prints: v bash 200ms
+
+```
+
+Then close with 3-6 sentences: name the pattern(s) at play (here: interceptor / middleware for the hook, ask-pattern for the oneshot channel, HITL interrupt gate for the overall behavior), and flag the blocking step as the part most likely to confuse someone.
+
+## Notes
+
+* If the user's topic has more than ~8-10 real stages, group related sub-steps under one numbered step rather than numbering everything - the diagram should stay scannable in one screen, not become an exhaustive trace.
+* If there's no natural branch/decision in the process, it's fine to omit step 4 (forks) and just run straight top-to-bottom.
+* If the user asks a follow-up like "zoom into step 3", redraw just that step as its own smaller diagram using the same conventions.
+
+## Rust codebases
+
+If the topic involves Rust - smart pointers (`Box`, `Rc`, `Arc`), interior mutability (`RefCell`, `Cell`, `Mutex`), lifetimes, ownership/borrowing/move semantics, `Drop`/RAII, trait objects (`dyn Trait`), or a borrow-checker error the user is debugging - read `references/rust.md` before drawing the diagram. It has ready-made templates for these exact patterns in the house style, including which parts are compile-time (lifetimes, monomorphized generics) versus runtime (RefCell panics, Mutex blocking, Rc/Arc refcounting, Drop order) - that distinction is usually the crux of the explanation, so make sure it's explicit in the diagram or the prose that follows it.
+
+If the user pastes their own code, adapt the closest template to their actual types/variable names rather than answering with the generic template as-is.