aihi-agent 0.1.0__tar.gz

aihi_agent-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+node_modules/
+.pnpm-store/
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.aihi/settings.local.json
+.aihi/audit.jsonl
+.DS_Store
+
+# Local legacy SQLite compatibility fixture and SQLite WAL sidecars.
+/tests/fixtures/session_schema_v1.sqlite3*
+
+# Superpowers working documents: local process artefacts, not project docs.
+/docs/superpowers/
+
+# Architecture decision records and RFC drafts are local working notes.
+/docs/adr/
+/docs/rfcs/

aihi_agent-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: aihi-agent
+Version: 0.1.0
+Summary: Recoverable provider-neutral Agent Runtime for AIHI
+License: MIT
+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: aihi-models<0.2,>=0.1
+Description-Content-Type: text/markdown
+
+# aihi-agent
+
+[English] | [简体中文](README.zh-CN.md)
+
+Provider-neutral, recoverable agent runtime for AIHI.
+
+`aihi-agent` turns model contracts into a durable execution system. It provides the loop, sessions, tools, policy, approvals, sandbox boundary, context management, integrations, and observability that an application can compose for a specific product.
+
+## Responsibilities
+
+- Run bounded model/tool turns with explicit runtime composition.
+- Persist an append-only event log and recover sessions after interruption.
+- Compile context and compact it into derived summaries without rewriting history.
+- Register and execute tools through policy, approvals, hooks, and a sandbox backend.
+- Integrate Skills, MCP servers, subagents, memory, artifacts, telemetry, replay, and evaluations.
+
+The package does **not** select a provider, implement a UI, provide a model router/gateway, or hide tool defaults. Applications pass those choices to `RuntimeBuilder`.
+
+## Architecture
+
+```text
+Model Provider (aihi-models)
+              │
+              ▼
+RuntimeBuilder ──► Runtime / RunCoordinator ──► EventStore
+              │                  │
+              │                  ├── ContextCompiler / Compaction
+              │                  ├── ToolRegistry ──► Policy ──► Approval
+              │                  │                         │
+              │                  │                         ▼
+              │                  └── Hooks ──► SandboxBackend ──► Tool
+              │
+              └── Skills / MCP / Subagents / Memory / Artifacts / Telemetry
+```
+
+The event store is the source of truth. Tool calls are recorded before execution and have exactly one result. An approval decision of `ASK` suspends the run so it can be resumed later.
+
+## Installation
+
+From the workspace:
+
+```bash
+uv sync
+```
+
+For a local editable install:
+
+```bash
+uv pip install -e packages/aihi/agent
+```
+
+`aihi-agent` requires Python 3.11+ and depends on `aihi-models` 0.1.x.
+
+## Minimal runtime
+
+```python
+from pathlib import Path
+
+from aihi.agent import HostBackend, InMemoryEventStore, ReadFileTool, RuntimeBuilder, Session
+from aihi.models import FakeProvider, FakeStep, Message
+
+provider = FakeProvider([FakeStep(text="I inspected the workspace.")])
+runtime = (
+    RuntimeBuilder(
+        provider=provider,
+        model="fake-model",
+        sandbox=HostBackend(Path.cwd(), unsafe=True),
+        tools=[ReadFileTool()],
+    )
+    .with_max_turns(20)
+    .build()
+)
+
+session = Session.create(
+    InMemoryEventStore(),
+    cwd=Path.cwd(),
+    provider="fake",
+    model="fake-model",
+)
+
+result = await runtime.coordinator.run(
+    session,
+    model=runtime.model,
+    user_message=Message.text("user", "Inspect this project."),
+)
+print(result.state)
+```
+
+For real applications, prefer an isolated backend when available. `HostBackend` is a controlled local execution backend, not a security isolation boundary, and requires an explicit `unsafe=True` acknowledgement.
+
+## Runtime composition
+
+`RuntimeBuilder` requires the important dependencies up front:
+
+- `provider` and `model`;
+- a `sandbox` backend;
+- the application-approved `tools` collection.
+
+Optional extensions are added explicitly with methods such as:
+
+- `.with_max_turns(...)` and `.with_context_window(...)`;
+- `.with_policy(...)`, `.with_approvals(...)`, and `.with_hooks(...)`;
+- `.with_skills(...)`, `.with_memory(...)`, `.with_compaction(...)`;
+- `.with_subagents(...)`, `.with_artifacts(...)`, and `.with_telemetry(...)`.
+
+The default coordinator turn budget is finite (`100`) and can be lowered for a product-specific safety envelope.
+
+## Core modules
+
+| Area | Main API |
+| --- | --- |
+| Runtime and runs | `Runtime`, `RuntimeBuilder`, `RunCoordinator`, `RunResult`, `RunState` |
+| Sessions and storage | `Session`, `EventStore`, `InMemoryEventStore`, `SQLiteEventStore`, `Event` |
+| Context | `ContextCompiler`, summaries, compaction generators |
+| Tools | `Tool`, `ToolSpec`, `ToolContext`, `ToolRegistry`, built-in file/shell tools |
+| Policy and approval | `PermissionMode`, `DefaultPolicyEngine`, `Approval`, approval resolvers |
+| Sandbox | `HostBackend`, `LocalIsolatedBackend`, `DockerBackend` |
+| Integrations | Skills, MCP, plugins, subagents, memory, artifacts |
+| Observability | `Telemetry`, `JsonlTelemetrySink`, `InMemoryTelemetrySink` |
+| Verification | replay, golden tasks, evals, and contract helpers |
+
+## Tool and approval model
+
+Tools are registered with explicit `ToolSpec` metadata. The policy engine decides whether an invocation is allowed, denied, or must ask for approval. Approval leases can scope a decision to a request, a tool, or a run according to the application policy.
+
+Use the built-in tools only with a sandbox and policy appropriate for the workspace. File reads, glob/grep, edits, writes, and shell execution should not be treated as interchangeable capabilities.
+
+## Observability
+
+Telemetry is an observation stream, not the event log. `JsonlTelemetrySink` emits redacted, bounded records and creates owner-only files by default. Use the event store for recovery and audit the telemetry stream for operational diagnosis; do not use UI output as a source of truth.
+
+## Development
+
+```bash
+uv run pytest packages/aihi/agent/tests
+uv run ruff check packages/aihi/agent
+uv run mypy
+uv run python -m build --wheel --no-isolation packages/aihi/agent
+```
+
+See the repository [architecture guide](../../../docs/ARCHITECTURE.md) and the [code-agent README](../code-agent/README.md) for an application-level composition.
+
+## Security model
+
+- Keep credentials in the application/provider boundary, never in prompts or event payloads.
+- Treat model output, tool arguments, Skills, MCP responses, and subagent output as untrusted.
+- Do not claim that `HostBackend` isolates a process; use `LocalIsolatedBackend` or `DockerBackend` when isolation is required.
+- Set a finite turn limit and review approval/policy defaults before exposing tools to a model.

aihi_agent-0.1.0/README.md

@@ -0,0 +1,148 @@
+# aihi-agent
+
+[English] | [简体中文](README.zh-CN.md)
+
+Provider-neutral, recoverable agent runtime for AIHI.
+
+`aihi-agent` turns model contracts into a durable execution system. It provides the loop, sessions, tools, policy, approvals, sandbox boundary, context management, integrations, and observability that an application can compose for a specific product.
+
+## Responsibilities
+
+- Run bounded model/tool turns with explicit runtime composition.
+- Persist an append-only event log and recover sessions after interruption.
+- Compile context and compact it into derived summaries without rewriting history.
+- Register and execute tools through policy, approvals, hooks, and a sandbox backend.
+- Integrate Skills, MCP servers, subagents, memory, artifacts, telemetry, replay, and evaluations.
+
+The package does **not** select a provider, implement a UI, provide a model router/gateway, or hide tool defaults. Applications pass those choices to `RuntimeBuilder`.
+
+## Architecture
+
+```text
+Model Provider (aihi-models)
+              │
+              ▼
+RuntimeBuilder ──► Runtime / RunCoordinator ──► EventStore
+              │                  │
+              │                  ├── ContextCompiler / Compaction
+              │                  ├── ToolRegistry ──► Policy ──► Approval
+              │                  │                         │
+              │                  │                         ▼
+              │                  └── Hooks ──► SandboxBackend ──► Tool
+              │
+              └── Skills / MCP / Subagents / Memory / Artifacts / Telemetry
+```
+
+The event store is the source of truth. Tool calls are recorded before execution and have exactly one result. An approval decision of `ASK` suspends the run so it can be resumed later.
+
+## Installation
+
+From the workspace:
+
+```bash
+uv sync
+```
+
+For a local editable install:
+
+```bash
+uv pip install -e packages/aihi/agent
+```
+
+`aihi-agent` requires Python 3.11+ and depends on `aihi-models` 0.1.x.
+
+## Minimal runtime
+
+```python
+from pathlib import Path
+
+from aihi.agent import HostBackend, InMemoryEventStore, ReadFileTool, RuntimeBuilder, Session
+from aihi.models import FakeProvider, FakeStep, Message
+
+provider = FakeProvider([FakeStep(text="I inspected the workspace.")])
+runtime = (
+    RuntimeBuilder(
+        provider=provider,
+        model="fake-model",
+        sandbox=HostBackend(Path.cwd(), unsafe=True),
+        tools=[ReadFileTool()],
+    )
+    .with_max_turns(20)
+    .build()
+)
+
+session = Session.create(
+    InMemoryEventStore(),
+    cwd=Path.cwd(),
+    provider="fake",
+    model="fake-model",
+)
+
+result = await runtime.coordinator.run(
+    session,
+    model=runtime.model,
+    user_message=Message.text("user", "Inspect this project."),
+)
+print(result.state)
+```
+
+For real applications, prefer an isolated backend when available. `HostBackend` is a controlled local execution backend, not a security isolation boundary, and requires an explicit `unsafe=True` acknowledgement.
+
+## Runtime composition
+
+`RuntimeBuilder` requires the important dependencies up front:
+
+- `provider` and `model`;
+- a `sandbox` backend;
+- the application-approved `tools` collection.
+
+Optional extensions are added explicitly with methods such as:
+
+- `.with_max_turns(...)` and `.with_context_window(...)`;
+- `.with_policy(...)`, `.with_approvals(...)`, and `.with_hooks(...)`;
+- `.with_skills(...)`, `.with_memory(...)`, `.with_compaction(...)`;
+- `.with_subagents(...)`, `.with_artifacts(...)`, and `.with_telemetry(...)`.
+
+The default coordinator turn budget is finite (`100`) and can be lowered for a product-specific safety envelope.
+
+## Core modules
+
+| Area | Main API |
+| --- | --- |
+| Runtime and runs | `Runtime`, `RuntimeBuilder`, `RunCoordinator`, `RunResult`, `RunState` |
+| Sessions and storage | `Session`, `EventStore`, `InMemoryEventStore`, `SQLiteEventStore`, `Event` |
+| Context | `ContextCompiler`, summaries, compaction generators |
+| Tools | `Tool`, `ToolSpec`, `ToolContext`, `ToolRegistry`, built-in file/shell tools |
+| Policy and approval | `PermissionMode`, `DefaultPolicyEngine`, `Approval`, approval resolvers |
+| Sandbox | `HostBackend`, `LocalIsolatedBackend`, `DockerBackend` |
+| Integrations | Skills, MCP, plugins, subagents, memory, artifacts |
+| Observability | `Telemetry`, `JsonlTelemetrySink`, `InMemoryTelemetrySink` |
+| Verification | replay, golden tasks, evals, and contract helpers |
+
+## Tool and approval model
+
+Tools are registered with explicit `ToolSpec` metadata. The policy engine decides whether an invocation is allowed, denied, or must ask for approval. Approval leases can scope a decision to a request, a tool, or a run according to the application policy.
+
+Use the built-in tools only with a sandbox and policy appropriate for the workspace. File reads, glob/grep, edits, writes, and shell execution should not be treated as interchangeable capabilities.
+
+## Observability
+
+Telemetry is an observation stream, not the event log. `JsonlTelemetrySink` emits redacted, bounded records and creates owner-only files by default. Use the event store for recovery and audit the telemetry stream for operational diagnosis; do not use UI output as a source of truth.
+
+## Development
+
+```bash
+uv run pytest packages/aihi/agent/tests
+uv run ruff check packages/aihi/agent
+uv run mypy
+uv run python -m build --wheel --no-isolation packages/aihi/agent
+```
+
+See the repository [architecture guide](../../../docs/ARCHITECTURE.md) and the [code-agent README](../code-agent/README.md) for an application-level composition.
+
+## Security model
+
+- Keep credentials in the application/provider boundary, never in prompts or event payloads.
+- Treat model output, tool arguments, Skills, MCP responses, and subagent output as untrusted.
+- Do not claim that `HostBackend` isolates a process; use `LocalIsolatedBackend` or `DockerBackend` when isolation is required.
+- Set a finite turn limit and review approval/policy defaults before exposing tools to a model.

aihi_agent-0.1.0/README.zh-CN.md

@@ -0,0 +1,71 @@
+# aihi-agent
+
+[English](README.md) | **简体中文**
+
+AIHI 的 Provider-neutral、可恢复 Agent Runtime。它把模型契约转换成带持久化、策略和安全边界的
+执行系统，供具体应用组合。
+
+## 职责
+
+- 通过显式 `RuntimeBuilder` 运行有界的 model/tool turns。
+- 追加事件日志并在中断后恢复 Session。
+- 编译上下文、预算保护和派生摘要压缩。
+- 通过 Policy、Approval、Hooks 和 Sandbox 执行工具。
+- 提供 Skill、MCP、Plugin、Subagent、Memory、Artifact、Telemetry、Replay 和 Eval 接入点。
+
+本包不选择 Provider、不实现 UI、不提供 Router/Gateway，也不隐藏工具默认值。
+
+## 架构
+
+```text
+aihi.models Provider
+        │
+RuntimeBuilder → RunCoordinator → EventStore
+        │              ├─ ContextCompiler / Compaction
+        │              ├─ ToolRegistry → Policy → Approval
+        │              └─ Hooks → SandboxBackend → Tool
+        └─ Skills / MCP / Subagents / Memory / Artifacts
+```
+
+事件存储是事实源。工具调用先落盘再执行，并且每个调用恰好有一个结果；Policy 返回 `ASK` 时
+Run 会挂起，等待应用层解决后恢复。
+
+## 安装与最小运行
+
+```bash
+uv sync
+uv pip install -e packages/aihi/agent
+```
+
+```python
+from aihi.agent import RuntimeBuilder
+
+runtime = (
+    RuntimeBuilder()
+    .with_provider(provider, model="my-model")
+    .with_sandbox(sandbox)
+    .with_tools(tool_registry)
+    .build()
+)
+```
+
+Provider、Sandbox 和 tools 必须由应用显式注入；不存在无条件选择这些依赖的
+`default_runtime()`。
+
+## 核心约束
+
+- 默认 loop 有最大 turns，防止无界消耗 token。
+- 读文件、Glob、Grep 等声明为并发安全的只读工具可并行执行；修改工具保持顺序。
+- Host backend 必须显式 `unsafe=true`。
+- Resume 使用首次 `run.started` 固化的 Provider、Model、Workspace、权限和预算。
+- 子 Agent 使用独立 Session，并只能获得父级权限、预算和 workspace 的更严格子集。
+
+## 开发
+
+```bash
+pytest packages/aihi/agent/tests
+ruff check packages/aihi/agent
+mypy packages/aihi/agent/src
+```
+
+参见 [架构文档](../../../docs/ARCHITECTURE.zh-CN.md) 和 [Coding Agent 文档](../code-agent/README.zh-CN.md)。

aihi_agent-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aihi-agent"
+version = "0.1.0"
+description = "Recoverable provider-neutral Agent Runtime for AIHI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+  "aihi-models>=0.1,<0.2",
+]
+
+classifiers = [
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[tool.uv.sources]
+aihi-models = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aihi"]
+artifacts = ["src/aihi/agent/py.typed"]