rungent 0.1.0__tar.gz

rungent-0.1.0/.gitignore

@@ -0,0 +1,73 @@
+# Python
+.venv/
+venv/
+.uv-cache/
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+dist/
+build/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Node / pnpm
+node_modules/
+.pnpm-store/
+.pnpm-debug.log*
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+*.tsbuildinfo
+
+# Docs / Next / Fumadocs
+.next/
+.turbo/
+.source/
+out/
+apps/docs/.next/
+apps/docs/.source/
+
+# Test & coverage (JS)
+coverage/
+*.lcov
+
+# Env & secrets
+.env
+.env.*
+!.env.example
+!.env.*.example
+*.pem
+*.key
+credentials.json
+secrets.json
+
+# OS / editors
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+*.swp
+*.swo
+*~
+
+# Local / misc
+*.log
+tmp/
+temp/
+.cache/
+.direnv/

rungent-0.1.0/LICENSE

@@ -0,0 +1,18 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 Rungent Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

rungent-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: rungent
+Version: 0.1.0
+Summary: A small, typed agent runtime for Python applications
+Project-URL: Homepage, https://github.com/rungent/rungent
+Project-URL: Documentation, https://github.com/rungent/rungent/tree/main/docs
+Project-URL: Repository, https://github.com/rungent/rungent
+Project-URL: Issues, https://github.com/rungent/rungent/issues
+Project-URL: Changelog, https://github.com/rungent/rungent/releases
+Author: Rungent Contributors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,fastapi,llm,sse,tool-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.10.0
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20.0; extra == 'dev'
+Requires-Dist: fastapi>=0.115.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.36; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115.0; extra == 'fastapi'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy[asyncio]>=2.0.36; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# Rungent
+
+Rungent is a small, typed agent runtime that embeds into an existing Python application. It
+standardizes tool calling, the harness loop, durable sessions and runs, user interactions,
+deterministic approval gates, and an SSE event protocol.
+
+Its headless activity protocol exposes model steps, safe public progress, tools, and interactions as
+persisted events. It never exposes raw provider reasoning or hidden chain of thought.
+
+```python
+from typing import Annotated
+
+from rungent import Agent, RunActivity, Runtime, ToolContext, ToolResult, tool
+from rungent.llm import OpenAICompatibleModel
+from rungent.store import MemoryStore
+
+
+@tool(effect="write", approval="never")
+async def move_place(
+    ctx: ToolContext,
+    name: Annotated[str, "Exact place name"],
+    day_number: Annotated[int | None, "Target day; null means unplanned"],
+) -> ToolResult:
+    await ctx.deps["trips"].move(ctx.resource["trip_id"], name, day_number)
+    return ToolResult(message=f"Moved {name}")
+
+
+agent = Agent(
+    name="trip_planner",
+    instructions="Help the user update their trip. Use tools for every change.",
+    tools=[move_place],
+    run_activity=lambda _ctx, _content: RunActivity(
+        message="Received the request",
+        waiting_message="Still preparing; no changes have been made",
+        long_wait_message="The request is detailed; still preparing",
+        continuation_message="Preparing the result",
+    ),
+)
+
+runtime = Runtime(
+    agents=[agent],
+    model=OpenAICompatibleModel.from_env(),
+    store=MemoryStore(),
+)
+```
+
+The canonical documentation lives in `docs/` and is rendered by the Fumadocs app in `apps/docs`.
+AI coding agents should start with [`RUNGENT.md`](RUNGENT.md); the running site also exposes
+`/llms.txt`, `/llms-full.txt`, and per-page raw Markdown under `/markdown/*`.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest -W error
+uv run ruff check src tests
+
+pnpm install
+pnpm dev:docs
+pnpm test
+pnpm build
+```
+
+## Release
+
+`rungent` (PyPI) and `@rungent/sdk` (npm) share one semver. Publishing is done by GitHub Actions
+on `v*` tags — do not `uv publish` / `npm publish` from your laptop.
+
+```bash
+./scripts/release.sh 0.2.0
+git push origin main --tags
+```
+
+One-time Trusted Publishing setup: see [`RELEASING.md`](RELEASING.md).

rungent-0.1.0/README.md

@@ -0,0 +1,74 @@
+# Rungent
+
+Rungent is a small, typed agent runtime that embeds into an existing Python application. It
+standardizes tool calling, the harness loop, durable sessions and runs, user interactions,
+deterministic approval gates, and an SSE event protocol.
+
+Its headless activity protocol exposes model steps, safe public progress, tools, and interactions as
+persisted events. It never exposes raw provider reasoning or hidden chain of thought.
+
+```python
+from typing import Annotated
+
+from rungent import Agent, RunActivity, Runtime, ToolContext, ToolResult, tool
+from rungent.llm import OpenAICompatibleModel
+from rungent.store import MemoryStore
+
+
+@tool(effect="write", approval="never")
+async def move_place(
+    ctx: ToolContext,
+    name: Annotated[str, "Exact place name"],
+    day_number: Annotated[int | None, "Target day; null means unplanned"],
+) -> ToolResult:
+    await ctx.deps["trips"].move(ctx.resource["trip_id"], name, day_number)
+    return ToolResult(message=f"Moved {name}")
+
+
+agent = Agent(
+    name="trip_planner",
+    instructions="Help the user update their trip. Use tools for every change.",
+    tools=[move_place],
+    run_activity=lambda _ctx, _content: RunActivity(
+        message="Received the request",
+        waiting_message="Still preparing; no changes have been made",
+        long_wait_message="The request is detailed; still preparing",
+        continuation_message="Preparing the result",
+    ),
+)
+
+runtime = Runtime(
+    agents=[agent],
+    model=OpenAICompatibleModel.from_env(),
+    store=MemoryStore(),
+)
+```
+
+The canonical documentation lives in `docs/` and is rendered by the Fumadocs app in `apps/docs`.
+AI coding agents should start with [`RUNGENT.md`](RUNGENT.md); the running site also exposes
+`/llms.txt`, `/llms-full.txt`, and per-page raw Markdown under `/markdown/*`.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest -W error
+uv run ruff check src tests
+
+pnpm install
+pnpm dev:docs
+pnpm test
+pnpm build
+```
+
+## Release
+
+`rungent` (PyPI) and `@rungent/sdk` (npm) share one semver. Publishing is done by GitHub Actions
+on `v*` tags — do not `uv publish` / `npm publish` from your laptop.
+
+```bash
+./scripts/release.sh 0.2.0
+git push origin main --tags
+```
+
+One-time Trusted Publishing setup: see [`RELEASING.md`](RELEASING.md).

rungent-0.1.0/RUNGENT.md

@@ -0,0 +1,99 @@
+# Rungent integration guide for coding agents
+
+This is the canonical short context for an AI coding agent integrating Rungent.
+
+1. Define one `Agent` for one product assistant. Do not introduce skills or routing unless the
+   product genuinely has multiple independent capability domains.
+2. Define business operations with `@tool`. The first parameter is `ToolContext`; all other typed
+   parameters become the model-facing JSON Schema.
+3. Declare `effect` and `approval` explicitly. Never infer safety from a function name.
+   Every `approval="always"` tool must provide a concrete `confirmation` string or callable that
+   identifies the affected object and impact; never ask users to approve only a generic tool title.
+   Equivalent successful non-read calls are deduplicated per Run; prefer a batch/count argument and
+   use `deduplicate=False` only when identical repeated writes are intentional.
+4. Put durable service factories in `ToolContext.deps`, stable resource identifiers in
+   `ToolContext.resource`, and read the accepted input from `ToolContext.current_input`. After
+   `request_input` resumes, `ToolContext.interaction_response`
+   contains the runtime-validated interaction ID, kind, prompt, and value for that response only;
+   declare `requires_interaction_response=True` when a host operation must reject model-invented
+   answers. Rungent exposes that tool only after a real answer and consumes the answer once.
+5. Use `Runtime` for session/run lifecycle. Do not write a second tool loop. The default bounded
+   loop allows 16 model steps. Retryable timeouts, transport failures, HTTP 408/429, and server
+   errors retry inside the same step up to three times; empty completions consume a new bounded
+   step and never become empty user messages.
+6. Use the FastAPI router from `rungent.fastapi` when exposing the assistant over HTTP. Run
+   creation returns `202` with a Run ID; subscribe separately so disconnecting the event stream
+   never cancels execution. Pass `Idempotency-Key` when a client may retry creation.
+7. Consume the SSE stream with `@rungent/sdk`. Do not parse provider-specific model chunks in the
+   frontend.
+8. Use `request_input` for missing information. Group two to eight independent, already-known
+   questions in one `form`; ask sequentially only when a later question depends on an earlier
+   answer. A `choice` may declare `multiple` and `allow_custom`; choice responses use
+   `{selected: string[], custom?: string}`. Form responses use `{answers: {question_id: value}}`.
+   All responses are validated by the runtime. Destructive approvals are generated by Rungent,
+   not by prompting the model to ask “confirm?”.
+9. Rungent exposes public work activity, not raw chain of thought. The model may call the built-in
+   `report_progress` alongside business tool calls during multi-step work, never as a dedicated
+   model step; model steps, tools, interactions, and progress are
+   persisted as ordered public events and projected by the SDK as `state.activities`.
+   Terminal Run events settle every unfinished activity; transport failures should call
+   `failRungentState` so a stale spinner can never survive an interrupted request.
+   Long-running host tools may call `await ctx.report_progress(message, public=...)`; Rungent
+   persists and streams each update while the tool is still executing. Updates from one tool call
+   share a stable activity ID, remain `running` while work continues, and replace one projected SDK
+   row; the ordered event log still retains every update for replay and audit.
+10. Add deterministic baseline cases before enabling a real model baseline. Export a
+   `BaselineSuite` and run `rungent baseline module:suite` in the host project.
+   Tool and interaction expectations are exact by default; use their `contains` match modes only
+   for live-model cases where safe retries or optional branches are acceptable, and always assert
+   final state.
+11. Read `docs/ai-reference.mdx` for the full public API and `examples/roasea/` for the reference
+    application pattern.
+12. Model user-sized business intents as atomic host tools. Stage large imports in the host
+   application, return their diff through `ToolResult.public`, clarify with `request_input`, and
+   commit the reviewed draft with one revision-checked atomic tool and one approval. Likewise, a
+   reversible “change every leg” request should be one host batch tool, not many single-item calls;
+   increasing the model-step limit cannot repair an undersized business interface.
+13. Model-facing tool results carry `tool_status: success|error`. Only explicit success envelopes
+    participate in deduplication; exceptions, timeouts, and `ToolResult(data={"ok": false})` remain
+    retryable. Call `client.cancel(runId)` before aborting the stream's `AbortSignal`; the cancel
+    endpoint terminates the active drive and persists `run.cancelled`. Treat `cancelled` as a
+    distinct terminal state.
+14. Add trusted provider-specific top-level request fields through
+    `OpenAICompatibleModel(extra_body=...)` or the `LLM_EXTRA_BODY` JSON object. Core request fields
+    cannot be overridden. For latency-sensitive Qwen runs, for example, use
+    `{"enable_thinking":false}`.
+15. Malformed or truncated tool-argument JSON is retried inside the same model step. Rungent resets
+    partial text and asks the provider for compact valid JSON before any tool can execute.
+16. A host tool may return `ToolResult.interaction=InteractionRequest(...)` with a frozen
+    continuation tool. Rungent persists and displays that question immediately, then executes the
+    typed `requires_interaction_response` continuation directly after a validated answer without
+    spending another model step. Use `allow_skip` only when skipping is safe for the workflow.
+17. Latency-sensitive agents should declare `run_activity`, returning public `RunActivity`
+    messages authored by the host application. Rungent emits the first activity immediately and,
+    while a provider stream is silent, updates the same persisted activity after three seconds and
+    every five seconds thereafter. Progress activities remain `running` until real model work
+    advances or the Run terminates; never use this channel for hidden reasoning. Products that
+    require finite deadlines may set per-attempt `model_step_timeout_seconds` and overall
+    `model_step_total_timeout_seconds`; retries receive a fresh per-attempt budget.
+18. Bounded-loop exhaustion keeps the numeric model-step limit in operator state and emits a safe
+   `run.failed` envelope with `code=model_step_limit_exceeded` and `retryable=true`. Product UIs
+    should localize recovery guidance from the code instead of displaying internals.
+19. `request_input` rejects numbered alternatives embedded in a `text` prompt; use `choice` so the
+    client can render typed options and a custom-answer row. Tool activities expose stable failure
+    codes, allowing product UIs to suppress or localize technical validation noise.
+19. Assistant message content is an opaque string to Rungent and `@rungent/sdk`. The host Agent owns
+   its writing-format instructions, and the product frontend owns Markdown parsing, sanitization,
+   link policy, and styling. Rungent intentionally does not declare a content format or ship a
+    renderer.
+20. A host tool may return `ToolResult.deferred=DeferredRequest(...)` for durable work that depends
+    on a browser or worker observation. Rungent persists the task binding, moves the Run to
+    `waiting_external`, and spends no model steps while waiting. Host code reports public progress
+    and calls `Runtime.resume_deferred` exactly once with an authoritative terminal result. The
+    runtime atomically claims and leases that resumption before returning to the model, so recovery
+    workers cannot mistake active continuation work for an interrupted Run. Connect
+    `external_task_canceller` when cancelling the Run must cancel host-owned work. Keep domain job
+    state in the application, not Rungent.
+21. Applications with an obvious deterministic entry path may declare `Agent.run_initializer`.
+    It returns at most one registered typed `ToolCall` before the first model step; Rungent applies
+    the same validation, interaction, deferred, and event rules as it does to model calls.

rungent-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "rungent"
+version = "0.1.0"
+description = "A small, typed agent runtime for Python applications"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [{ name = "Rungent Contributors" }]
+keywords = ["agent", "llm", "tool-calling", "fastapi", "sse"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.28.0",
+  "pydantic>=2.10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/rungent/rungent"
+Documentation = "https://github.com/rungent/rungent/tree/main/docs"
+Repository = "https://github.com/rungent/rungent"
+Issues = "https://github.com/rungent/rungent/issues"
+Changelog = "https://github.com/rungent/rungent/releases"
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.115.0"]
+sqlalchemy = ["sqlalchemy[asyncio]>=2.0.36"]
+dev = [
+  "aiosqlite>=0.20.0",
+  "fastapi>=0.115.0",
+  "pytest>=8.3.0",
+  "pytest-asyncio>=0.24.0",
+  "pyright>=1.1.0",
+  "ruff>=0.8.0",
+  "sqlalchemy[asyncio]>=2.0.36",
+]
+
+[project.scripts]
+rungent = "rungent.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rungent"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src/rungent",
+  "/README.md",
+  "/RUNGENT.md",
+  "/LICENSE",
+  "/pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+filterwarnings = ["error"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "standard"
+venvPath = "."
+venv = ".venv"
+extraPaths = ["src"]

rungent-0.1.0/src/rungent/RUNGENT.md

@@ -0,0 +1,99 @@
+# Rungent integration guide for coding agents
+
+This is the canonical short context for an AI coding agent integrating Rungent.
+
+1. Define one `Agent` for one product assistant. Do not introduce skills or routing unless the
+   product genuinely has multiple independent capability domains.
+2. Define business operations with `@tool`. The first parameter is `ToolContext`; all other typed
+   parameters become the model-facing JSON Schema.
+3. Declare `effect` and `approval` explicitly. Never infer safety from a function name.
+   Every `approval="always"` tool must provide a concrete `confirmation` string or callable that
+   identifies the affected object and impact; never ask users to approve only a generic tool title.
+   Equivalent successful non-read calls are deduplicated per Run; prefer a batch/count argument and
+   use `deduplicate=False` only when identical repeated writes are intentional.
+4. Put durable service factories in `ToolContext.deps`, stable resource identifiers in
+   `ToolContext.resource`, and read the accepted input from `ToolContext.current_input`. After
+   `request_input` resumes, `ToolContext.interaction_response`
+   contains the runtime-validated interaction ID, kind, prompt, and value for that response only;
+   declare `requires_interaction_response=True` when a host operation must reject model-invented
+   answers. Rungent exposes that tool only after a real answer and consumes the answer once.
+5. Use `Runtime` for session/run lifecycle. Do not write a second tool loop. The default bounded
+   loop allows 16 model steps. Retryable timeouts, transport failures, HTTP 408/429, and server
+   errors retry inside the same step up to three times; empty completions consume a new bounded
+   step and never become empty user messages.
+6. Use the FastAPI router from `rungent.fastapi` when exposing the assistant over HTTP. Run
+   creation returns `202` with a Run ID; subscribe separately so disconnecting the event stream
+   never cancels execution. Pass `Idempotency-Key` when a client may retry creation.
+7. Consume the SSE stream with `@rungent/sdk`. Do not parse provider-specific model chunks in the
+   frontend.
+8. Use `request_input` for missing information. Group two to eight independent, already-known
+   questions in one `form`; ask sequentially only when a later question depends on an earlier
+   answer. A `choice` may declare `multiple` and `allow_custom`; choice responses use
+   `{selected: string[], custom?: string}`. Form responses use `{answers: {question_id: value}}`.
+   All responses are validated by the runtime. Destructive approvals are generated by Rungent,
+   not by prompting the model to ask “confirm?”.
+9. Rungent exposes public work activity, not raw chain of thought. The model may call the built-in
+   `report_progress` alongside business tool calls during multi-step work, never as a dedicated
+   model step; model steps, tools, interactions, and progress are
+   persisted as ordered public events and projected by the SDK as `state.activities`.
+   Terminal Run events settle every unfinished activity; transport failures should call
+   `failRungentState` so a stale spinner can never survive an interrupted request.
+   Long-running host tools may call `await ctx.report_progress(message, public=...)`; Rungent
+   persists and streams each update while the tool is still executing. Updates from one tool call
+   share a stable activity ID, remain `running` while work continues, and replace one projected SDK
+   row; the ordered event log still retains every update for replay and audit.
+10. Add deterministic baseline cases before enabling a real model baseline. Export a
+   `BaselineSuite` and run `rungent baseline module:suite` in the host project.
+   Tool and interaction expectations are exact by default; use their `contains` match modes only
+   for live-model cases where safe retries or optional branches are acceptable, and always assert
+   final state.
+11. Read `docs/ai-reference.mdx` for the full public API and `examples/roasea/` for the reference
+    application pattern.
+12. Model user-sized business intents as atomic host tools. Stage large imports in the host
+   application, return their diff through `ToolResult.public`, clarify with `request_input`, and
+   commit the reviewed draft with one revision-checked atomic tool and one approval. Likewise, a
+   reversible “change every leg” request should be one host batch tool, not many single-item calls;
+   increasing the model-step limit cannot repair an undersized business interface.
+13. Model-facing tool results carry `tool_status: success|error`. Only explicit success envelopes
+    participate in deduplication; exceptions, timeouts, and `ToolResult(data={"ok": false})` remain
+    retryable. Call `client.cancel(runId)` before aborting the stream's `AbortSignal`; the cancel
+    endpoint terminates the active drive and persists `run.cancelled`. Treat `cancelled` as a
+    distinct terminal state.
+14. Add trusted provider-specific top-level request fields through
+    `OpenAICompatibleModel(extra_body=...)` or the `LLM_EXTRA_BODY` JSON object. Core request fields
+    cannot be overridden. For latency-sensitive Qwen runs, for example, use
+    `{"enable_thinking":false}`.
+15. Malformed or truncated tool-argument JSON is retried inside the same model step. Rungent resets
+    partial text and asks the provider for compact valid JSON before any tool can execute.
+16. A host tool may return `ToolResult.interaction=InteractionRequest(...)` with a frozen
+    continuation tool. Rungent persists and displays that question immediately, then executes the
+    typed `requires_interaction_response` continuation directly after a validated answer without
+    spending another model step. Use `allow_skip` only when skipping is safe for the workflow.
+17. Latency-sensitive agents should declare `run_activity`, returning public `RunActivity`
+    messages authored by the host application. Rungent emits the first activity immediately and,
+    while a provider stream is silent, updates the same persisted activity after three seconds and
+    every five seconds thereafter. Progress activities remain `running` until real model work
+    advances or the Run terminates; never use this channel for hidden reasoning. Products that
+    require finite deadlines may set per-attempt `model_step_timeout_seconds` and overall
+    `model_step_total_timeout_seconds`; retries receive a fresh per-attempt budget.
+18. Bounded-loop exhaustion keeps the numeric model-step limit in operator state and emits a safe
+   `run.failed` envelope with `code=model_step_limit_exceeded` and `retryable=true`. Product UIs
+    should localize recovery guidance from the code instead of displaying internals.
+19. `request_input` rejects numbered alternatives embedded in a `text` prompt; use `choice` so the
+    client can render typed options and a custom-answer row. Tool activities expose stable failure
+    codes, allowing product UIs to suppress or localize technical validation noise.
+19. Assistant message content is an opaque string to Rungent and `@rungent/sdk`. The host Agent owns
+   its writing-format instructions, and the product frontend owns Markdown parsing, sanitization,
+   link policy, and styling. Rungent intentionally does not declare a content format or ship a
+    renderer.
+20. A host tool may return `ToolResult.deferred=DeferredRequest(...)` for durable work that depends
+    on a browser or worker observation. Rungent persists the task binding, moves the Run to
+    `waiting_external`, and spends no model steps while waiting. Host code reports public progress
+    and calls `Runtime.resume_deferred` exactly once with an authoritative terminal result. The
+    runtime atomically claims and leases that resumption before returning to the model, so recovery
+    workers cannot mistake active continuation work for an interrupted Run. Connect
+    `external_task_canceller` when cancelling the Run must cancel host-owned work. Keep domain job
+    state in the application, not Rungent.
+21. Applications with an obvious deterministic entry path may declare `Agent.run_initializer`.
+    It returns at most one registered typed `ToolCall` before the first model step; Rungent applies
+    the same validation, interaction, deferred, and event rules as it does to model calls.

rungent-0.1.0/src/rungent/__init__.py

@@ -0,0 +1,30 @@
+from .agent import Agent, RunActivity
+from .runtime import Runtime
+from .state import (
+    DeferredRequest,
+    Identity,
+    InteractionRequest,
+    InteractionResponse,
+    ToolContinuation,
+    ToolResult,
+    TrustedInteractionResponse,
+)
+from .tools import ApprovalPolicy, Tool, ToolContext, ToolEffect, tool
+
+__all__ = [
+    "Agent",
+    "ApprovalPolicy",
+    "DeferredRequest",
+    "Identity",
+    "InteractionRequest",
+    "InteractionResponse",
+    "Runtime",
+    "RunActivity",
+    "Tool",
+    "ToolContext",
+    "ToolContinuation",
+    "ToolEffect",
+    "ToolResult",
+    "TrustedInteractionResponse",
+    "tool",
+]

rungent-0.1.0/src/rungent/acs.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .state import new_id, now
+
+
+class Event(BaseModel):
+    v: int = 1
+    id: str = Field(default_factory=lambda: new_id("evt"))
+    seq: int
+    type: str
+    session_id: str
+    run_id: str
+    created_at: datetime = Field(default_factory=now)
+    data: dict[str, Any] = Field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class EventEmitter:
+    session_id: str
+    run_id: str
+    sequence: int = 0
+
+    def emit(self, event_type: str, **data: Any) -> Event:
+        self.sequence += 1
+        return Event(
+            seq=self.sequence,
+            type=event_type,
+            session_id=self.session_id,
+            run_id=self.run_id,
+            data=data,
+        )
+
+
+def encode_sse(event: Event) -> str:
+    return f"data: {json.dumps(event.model_dump(mode='json'), ensure_ascii=False)}\n\n"