orcakit-harness-agent 0.7.0__tar.gz

orcakit_harness_agent-0.7.0/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# uv
+# Keep uv.lock tracked; ignore only local downloads
+.uv/
+
+# hatch-vcs auto-generated version file (single source of truth = git tag)
+src/harness_agent/_version.py
+
+# Local agent runtime artifacts (when using examples/)
+agent_root/
+.e2e_root/
+.cos_e2e_root/
+.init_demo_root/
+.skills_tour_root/
+*.sqlite
+*.sqlite-journal
+sessions/
+
+# Direnv
+.envrc
+.env
+.env.local

orcakit_harness_agent-0.7.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+
+- `teams`: `@agent` mentions now resolve peer agents by name (same path as `ask_agent` sync) via `resolve_mention_targets` / `ask_peer_sync`; hosts can call `TeamManager.prepare_request_mentions` for full request handling.
+
+### Added
+- MCP server integration via `langchain-mcp-adapters`: `HarnessAgentConfig.mcp_server_configs`,
+  `mcp_default_servers`, per-request opt-in on `ChatRequest` (`mcp_servers` / `mcp_use_default`),
+  and `HarnessAgentManager` shared `mcp_server_configs` merged into each agent.
+- `harness_agent.providers` module: `ModelPreset`, `ProviderPreset` dataclasses and `load_provider_templates(templates_path=None)` — core layer, no CLI dependency.
+- `AgentManager.list_provider_templates(templates_path=None)` — returns built-in or custom provider presets.
+- `ChatRequest` per-request `skills` filter and optional `agent_id` (written to `RunnableConfig.configurable`).
+- `SkillFilterMiddleware` restricts the skills system prompt to `ChatRequest.skills` when set.
+
+### Changed
+- Renamed internal package `harness_agent.models` → `harness_agent.llm` (`ChatModelFactory` import path).
+- Bootstrap middleware stays registered when `bootstrap_enabled=True` even if `BOOTSTRAP.md` is seeded after agent construction; `HarnessAgentManager.create_agent(..., init_workspace=True)` recompiles the graph after seeding. Marker detection uses the agent backend (`/.bootstrapped`); completing onboarding auto-writes the marker when `USER.md` is updated.
+- `HarnessAgentManager.create_agent()` auto-generated `agent_id` is now a 6-character
+  lowercase alphanumeric string (was uuid4).
+- `ProviderConfig` now has a required `id` field (was the dict key in `HarnessAgentConfig.providers`).
+- `HarnessAgentConfig.providers` is now `list[ProviderConfig]` instead of `dict[str, ProviderConfig]`.
+  Old dict-format JSON configs are automatically migrated on load via `from_dict`.
+- `ChatModelFactory` now accepts `list[ProviderConfig]` instead of `HarnessAgentConfig`.
+- `HarnessAgent` accepts an optional `model_factory: ChatModelFactory` keyword argument.
+  When provided, the factory is reused directly instead of building a new one.
+- `AgentManager` accepts an optional `providers: list[ProviderConfig]` constructor argument.
+  When provided, a shared `ChatModelFactory` is built once and reused for all managed agents.
+- **Breaking:** `HarnessAgentManager` CRUD methods renamed for clarity: `create()` → `create_agent()`,
+  `get()` → `get_agent()`, `remove()` → `remove_agent()`, `list()` → `list_agents()`.
+- `HarnessAgentManager.create_agent()` now builds and caches `HarnessAgent` eagerly (previously built lazily per-stream).
+  The cached instance is reused across all subsequent `stream()` calls for that agent.
+- `HarnessAgentManager.create_agent()` gains `init_workspace: bool = True` — workspace is initialised automatically on agent creation.
+- `HarnessAgentManager.remove_agent()` now calls `agent.close()` to release resources (SqliteSaver, etc.) before removing the entry.
+- `AgentManager` gains a `close()` method that closes all cached agents and clears the registry.
+- `AgentManager` supports both sync (`with`) and async (`async with`) context manager protocols.
+- `AgentEntry` gains an `agent` field exposing the cached `HarnessAgent` instance (e.g. `entry.agent.backend` for direct backend access).
+- `provider_template.json` moved from `builtin/providers/` to `providers/`.
+
+### Removed
+- `harness_agent.builtin.providers` compatibility shim (use `harness_agent.providers` instead).
+- `cli/providers/registry.py` is now a thin re-export of core types.
+- CLI: `harness-agent`（无参数）现在直接进入 chat REPL，不再显示 help 文本（`--help` 行为不变）
+- CLI: 启动时自动加载 `.env` 文件（项目目录 `<cwd>/.env` 优先，回退到 `~/.harness-agent/.env`；不覆盖已有 shell 环境变量）
+- CLI: REPL 新增 `/env` 命令，支持 `set`/`get`/`list`/`unset`/`reload` 操作，写入 `~/.harness-agent/.env`
+- CLI: `/model` 改为交互式编号列表选择，去掉 `/model <name>` 直接设置
+- CLI: 自动补全 slash 命令列表改为从命令注册表动态生成，修复缺少 `/env`、`/agent` 等命令的问题
+- `python-dotenv>=1.0` 加入 `cli` optional extra 依赖

orcakit_harness_agent-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OrcaKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orcakit_harness_agent-0.7.0/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: orcakit-harness-agent
+Version: 0.7.0
+Summary: Production-grade Harness Agent built on top of LangChain Deep Agents.
+Project-URL: Homepage, https://github.com/orcakit/harness-agent
+Project-URL: Repository, https://github.com/orcakit/harness-agent
+Project-URL: Issues, https://github.com/orcakit/harness-agent/issues
+Project-URL: Changelog, https://github.com/orcakit/harness-agent/blob/main/CHANGELOG.md
+Author: orcakit
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,deep-agents,harness,langchain,langgraph,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: deepagents<1.0,>=0.6
+Requires-Dist: harness-browser>=0.1.1
+Requires-Dist: harness-memory>=0.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: langchain-anthropic<2.0,>=1.4
+Requires-Dist: langchain-core<2.0,>=1.4
+Requires-Dist: langchain-mcp-adapters>=0.3.0
+Requires-Dist: langchain-openai>=0.3
+Requires-Dist: langchain<2.0,>=1.3
+Requires-Dist: langgraph-checkpoint-sqlite>=2.0
+Requires-Dist: langgraph<2.0,>=1.0
+Requires-Dist: markdownify>=0.13
+Requires-Dist: mcp>=1.27.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: acp
+Requires-Dist: agent-client-protocol>=0.9.0; extra == 'acp'
+Requires-Dist: psutil>=5.9; extra == 'acp'
+Provides-Extra: bedrock
+Requires-Dist: langchain-aws>=0.2; extra == 'bedrock'
+Provides-Extra: brave
+Requires-Dist: langchain-community>=0.3; extra == 'brave'
+Provides-Extra: cli
+Requires-Dist: click>=8.1; extra == 'cli'
+Requires-Dist: prompt-toolkit>=3.0; extra == 'cli'
+Requires-Dist: python-dotenv>=1.0; extra == 'cli'
+Requires-Dist: rich>=13.0; extra == 'cli'
+Provides-Extra: cos
+Requires-Dist: cos-python-sdk-v5>=1.9; extra == 'cos'
+Provides-Extra: desktop
+Requires-Dist: mss>=9.0; extra == 'desktop'
+Provides-Extra: google-search
+Requires-Dist: google-api-python-client>=2.0; extra == 'google-search'
+Requires-Dist: langchain-community>=0.3; extra == 'google-search'
+Provides-Extra: observability
+Requires-Dist: langfuse>=4.9.0; extra == 'observability'
+Provides-Extra: remote-backends
+Requires-Dist: deepagents-backends>=0.2; (python_version >= '3.12') and extra == 'remote-backends'
+Provides-Extra: tavily
+Requires-Dist: langchain-tavily>=0.1; extra == 'tavily'
+Provides-Extra: web-search-all
+Requires-Dist: google-api-python-client>=2.0; extra == 'web-search-all'
+Requires-Dist: langchain-community>=0.3; extra == 'web-search-all'
+Requires-Dist: langchain-tavily>=0.1; extra == 'web-search-all'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/images/banner.jpeg" alt="Harness Agent Banner" width="100%" />
+</p>
+
+<h1 align="center">Harness Agent</h1>
+
+<p align="center">
+  <strong>Production-grade AI agent platform built on LangChain Deep Agents.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/orcakit-harness-agent/"><img src="https://img.shields.io/pypi/v/orcakit-harness-agent" alt="PyPI" /></a>
+  <a href="https://github.com/orcakit/harness-agent/actions/workflows/ci.yml"><img src="https://github.com/orcakit/harness-agent/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+</p>
+
+<p align="center">
+  <b>English</b> · <a href="README_CN.md">中文</a>
+</p>
+
+---
+
+## Highlights
+
+- **Deep Agent Architecture** — Built on LangGraph with hierarchical agent routing, tool orchestration, and stateful conversation management
+- **Multi-Agent Management** — `AgentManager` registry with metadata/tags, per-thread cancel, and id-based stream routing
+- **Multi-Model Support** — OpenAI, Anthropic, AWS Bedrock, and any OpenAI-compatible endpoint out of the box; 17 provider presets in a user-editable JSON template
+- **Built-in Tool Ecosystem** — Browser automation, desktop screenshots, web search (Tavily/Brave/Google/Kimi), and extensible skill system
+- **Production Ready** — Checkpoint persistence, configurable backends (SQLite, S3, COS, PostgreSQL), and structured logging
+- **Terminal-First CLI** — Rich interactive chat interface with skill management, config wizard, and workspace initialization
+
+---
+
+## Overview
+
+Harness Agent is an open-source AI agent framework that provides a complete runtime for building, deploying, and managing autonomous AI agents. It wraps LangChain Deep Agents with batteries-included tooling: multi-provider model routing, persistent memory via [harness-memory](https://github.com/orcakit/harness-memory), browser automation via [harness-browser](https://github.com/orcakit/harness-browser), and a terminal CLI for interactive use.
+
+The project is a single Python package with an optional CLI extra:
+
+| Install | Description |
+|---------|-------------|
+| `pip install orcakit-harness-agent` | Core SDK — agent runtime, model routing, tools, skills, backends |
+| `pip install orcakit-harness-agent[cli]` | Adds the terminal CLI — interactive chat, config, skill management |
+
+---
+
+## Core Technology
+
+| Layer | Technology | Purpose |
+|-------|-----------|---------|
+| Agent Runtime | [LangGraph](https://github.com/langchain-ai/langgraph) + [Deep Agents](https://pypi.org/project/deepagents/) | Stateful graph execution with hierarchical agent routing |
+| Model Providers | LangChain model integrations | Unified interface for OpenAI, Anthropic, Bedrock, and custom endpoints |
+| Memory | [harness-memory](https://github.com/orcakit/harness-memory) | Hierarchical recall with FTS search and pluggable backends |
+| Browser | [harness-browser](https://github.com/orcakit/harness-browser) | CDP-based browser automation with profile-persistent login |
+| Checkpointing | LangGraph Checkpoint + SQLite/Postgres | Conversation state persistence across sessions |
+| CLI Framework | Click + Rich + Textual | Terminal UI with streaming output and rich formatting |
+
+---
+
+## Features
+
+### Agent Runtime
+- Hierarchical agent routing with configurable delegation
+- **`AgentManager`** — in-memory registry for creating and managing multiple agents by `agent_id`
+- Stateful conversation management with checkpoint persistence
+- Per-thread stream cancellation via `manager.cancel(agent_id, thread_id)`
+- Middleware pipeline for request/response interception
+- Configurable system prompts and persona management
+
+### Model Routing
+- **OpenAI** — GPT-4o, GPT-4, GPT-3.5, and any compatible endpoint
+- **Anthropic** — Claude 4 Sonnet, Claude 4 Opus, Claude 3.5 family
+- **AWS Bedrock** — Claude, Titan, and other Bedrock models
+- **Custom** — Any OpenAI-compatible API via base URL configuration
+
+### Built-in Tools
+- **Browser Automation** — Navigate, click, type, screenshot via harness-browser
+- **Desktop Screenshot** — Full-screen capture for visual context
+- **Web Search** — Tavily, Brave, Google, Kimi (auto-detect or explicit selection)
+- **Extensible Skills** — Custom tool registration with typed schemas
+
+### Storage Backends
+- **SQLite** — Zero-config local persistence (default)
+- **Tencent Cloud COS** — Object storage for attachments and artifacts
+- **Remote Backends** — S3, PostgreSQL, Azure, GCS, MongoDB, Redis via `deepagents-backends`
+
+### CLI
+- Interactive streaming chat with rich markdown rendering
+- Workspace initialization (`harness-agent init`)
+- Provider configuration wizard (`harness-agent config provider add`)
+- Skill management and discovery
+
+---
+
+## Quick Start
+
+```bash
+# Install the CLI (includes core SDK)
+pip install orcakit-harness-agent[cli]
+
+# Initialize workspace
+harness-agent init
+
+# Configure a model provider
+harness-agent config provider add
+
+# Start chatting
+harness-agent chat
+```
+
+### Programmatic Usage
+
+```python
+from harness_agent import HarnessAgentManager, HarnessAgentConfig, ProviderConfig, ChatRequest
+
+config = HarnessAgentConfig(
+    workspace_dir="./workspace",
+    providers=[ProviderConfig(id="openai", api_key="sk-...", models=["gpt-4o"])],
+)
+
+manager = HarnessAgentManager()
+entry = manager.create_agent(config)
+
+async for chunk in manager.stream(entry.agent_id, ChatRequest(messages="Hello!")):
+    print(chunk.content, end="", flush=True)
+```
+
+> **Advanced:** For direct backend operations, access the cached agent via `entry.agent`.
+> `HarnessAgent` can also be constructed directly, but `AgentManager` is the recommended
+> entry point for all new code.
+
+### Multi-Agent Management
+
+```python
+from harness_agent import HarnessAgentManager, HarnessAgentConfig, ProviderConfig
+
+manager = HarnessAgentManager()
+
+# Register agents with metadata and tags
+entry = manager.create_agent(
+    config,
+    metadata={"tenant": "acme", "env": "prod"},
+    tags=["fast", "gpt4o"],
+)
+
+# Query agents by metadata / tags
+agents = manager.list_agents(metadata={"env": "prod"}, tags=["fast"])
+
+# Stream by agent_id
+async for chunk in manager.stream(entry.agent_id, request):
+    print(chunk)
+
+# Cancel mid-stream
+manager.cancel(entry.agent_id, request.thread_id)
+```
+
+---
+
+## Architecture
+
+```
+src/harness_agent/          Core SDK — agent runtime, model routing, tools, skills, backends
+src/harness_agent/cli/      Terminal CLI — thin view layer over the SDK
+```
+
+The CLI is a thin view layer that delegates all agent logic to the core SDK. This separation enables future UIs (web, IDE extensions) to reuse the same SDK.
+
+---
+
+## Development
+
+**Prerequisites:** Python 3.11+, [uv](https://docs.astral.sh/uv/)
+
+```bash
+git clone https://github.com/orcakit/harness-agent.git
+cd harness-agent
+make install          # install dev dependencies
+make all              # lint + typecheck + test (CI ship bar)
+```
+
+| Command | Description |
+|---------|-------------|
+| `make lint` | Ruff check + format check |
+| `make format` | Auto-fix and format |
+| `make typecheck` | mypy strict |
+| `make test` | pytest with coverage |
+| `make build` | Build wheel + sdist |
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and run `make all` before opening a PR.
+
+Security issues: see [SECURITY.md](SECURITY.md).
+
+---
+
+## Release
+
+Tag `v<version>` (e.g., `v0.2.0`) to trigger a PyPI release via GitHub Actions with trusted publishing.
+
+---
+
+## Related Projects
+
+| Project | Description |
+|---------|-------------|
+| [orca (Octop)](https://github.com/orcakit/orca) | Self-hosted multi-user AI control plane |
+| [harness-memory](https://github.com/orcakit/harness-memory) | Pluggable memory system with hierarchical recall and FTS |
+| [harness-browser](https://github.com/orcakit/harness-browser) | AI-friendly browser automation via CDP |
+| [harness-gateway](https://github.com/orcakit/harness-gateway) | Multi-platform IM channel bridge for AI agents |
+
+---
+
+## License
+
+[MIT](LICENSE)

orcakit_harness_agent-0.7.0/README.md

@@ -0,0 +1,219 @@
+<p align="center">
+  <img src="assets/images/banner.jpeg" alt="Harness Agent Banner" width="100%" />
+</p>
+
+<h1 align="center">Harness Agent</h1>
+
+<p align="center">
+  <strong>Production-grade AI agent platform built on LangChain Deep Agents.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/orcakit-harness-agent/"><img src="https://img.shields.io/pypi/v/orcakit-harness-agent" alt="PyPI" /></a>
+  <a href="https://github.com/orcakit/harness-agent/actions/workflows/ci.yml"><img src="https://github.com/orcakit/harness-agent/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+</p>
+
+<p align="center">
+  <b>English</b> · <a href="README_CN.md">中文</a>
+</p>
+
+---
+
+## Highlights
+
+- **Deep Agent Architecture** — Built on LangGraph with hierarchical agent routing, tool orchestration, and stateful conversation management
+- **Multi-Agent Management** — `AgentManager` registry with metadata/tags, per-thread cancel, and id-based stream routing
+- **Multi-Model Support** — OpenAI, Anthropic, AWS Bedrock, and any OpenAI-compatible endpoint out of the box; 17 provider presets in a user-editable JSON template
+- **Built-in Tool Ecosystem** — Browser automation, desktop screenshots, web search (Tavily/Brave/Google/Kimi), and extensible skill system
+- **Production Ready** — Checkpoint persistence, configurable backends (SQLite, S3, COS, PostgreSQL), and structured logging
+- **Terminal-First CLI** — Rich interactive chat interface with skill management, config wizard, and workspace initialization
+
+---
+
+## Overview
+
+Harness Agent is an open-source AI agent framework that provides a complete runtime for building, deploying, and managing autonomous AI agents. It wraps LangChain Deep Agents with batteries-included tooling: multi-provider model routing, persistent memory via [harness-memory](https://github.com/orcakit/harness-memory), browser automation via [harness-browser](https://github.com/orcakit/harness-browser), and a terminal CLI for interactive use.
+
+The project is a single Python package with an optional CLI extra:
+
+| Install | Description |
+|---------|-------------|
+| `pip install orcakit-harness-agent` | Core SDK — agent runtime, model routing, tools, skills, backends |
+| `pip install orcakit-harness-agent[cli]` | Adds the terminal CLI — interactive chat, config, skill management |
+
+---
+
+## Core Technology
+
+| Layer | Technology | Purpose |
+|-------|-----------|---------|
+| Agent Runtime | [LangGraph](https://github.com/langchain-ai/langgraph) + [Deep Agents](https://pypi.org/project/deepagents/) | Stateful graph execution with hierarchical agent routing |
+| Model Providers | LangChain model integrations | Unified interface for OpenAI, Anthropic, Bedrock, and custom endpoints |
+| Memory | [harness-memory](https://github.com/orcakit/harness-memory) | Hierarchical recall with FTS search and pluggable backends |
+| Browser | [harness-browser](https://github.com/orcakit/harness-browser) | CDP-based browser automation with profile-persistent login |
+| Checkpointing | LangGraph Checkpoint + SQLite/Postgres | Conversation state persistence across sessions |
+| CLI Framework | Click + Rich + Textual | Terminal UI with streaming output and rich formatting |
+
+---
+
+## Features
+
+### Agent Runtime
+- Hierarchical agent routing with configurable delegation
+- **`AgentManager`** — in-memory registry for creating and managing multiple agents by `agent_id`
+- Stateful conversation management with checkpoint persistence
+- Per-thread stream cancellation via `manager.cancel(agent_id, thread_id)`
+- Middleware pipeline for request/response interception
+- Configurable system prompts and persona management
+
+### Model Routing
+- **OpenAI** — GPT-4o, GPT-4, GPT-3.5, and any compatible endpoint
+- **Anthropic** — Claude 4 Sonnet, Claude 4 Opus, Claude 3.5 family
+- **AWS Bedrock** — Claude, Titan, and other Bedrock models
+- **Custom** — Any OpenAI-compatible API via base URL configuration
+
+### Built-in Tools
+- **Browser Automation** — Navigate, click, type, screenshot via harness-browser
+- **Desktop Screenshot** — Full-screen capture for visual context
+- **Web Search** — Tavily, Brave, Google, Kimi (auto-detect or explicit selection)
+- **Extensible Skills** — Custom tool registration with typed schemas
+
+### Storage Backends
+- **SQLite** — Zero-config local persistence (default)
+- **Tencent Cloud COS** — Object storage for attachments and artifacts
+- **Remote Backends** — S3, PostgreSQL, Azure, GCS, MongoDB, Redis via `deepagents-backends`
+
+### CLI
+- Interactive streaming chat with rich markdown rendering
+- Workspace initialization (`harness-agent init`)
+- Provider configuration wizard (`harness-agent config provider add`)
+- Skill management and discovery
+
+---
+
+## Quick Start
+
+```bash
+# Install the CLI (includes core SDK)
+pip install orcakit-harness-agent[cli]
+
+# Initialize workspace
+harness-agent init
+
+# Configure a model provider
+harness-agent config provider add
+
+# Start chatting
+harness-agent chat
+```
+
+### Programmatic Usage
+
+```python
+from harness_agent import HarnessAgentManager, HarnessAgentConfig, ProviderConfig, ChatRequest
+
+config = HarnessAgentConfig(
+    workspace_dir="./workspace",
+    providers=[ProviderConfig(id="openai", api_key="sk-...", models=["gpt-4o"])],
+)
+
+manager = HarnessAgentManager()
+entry = manager.create_agent(config)
+
+async for chunk in manager.stream(entry.agent_id, ChatRequest(messages="Hello!")):
+    print(chunk.content, end="", flush=True)
+```
+
+> **Advanced:** For direct backend operations, access the cached agent via `entry.agent`.
+> `HarnessAgent` can also be constructed directly, but `AgentManager` is the recommended
+> entry point for all new code.
+
+### Multi-Agent Management
+
+```python
+from harness_agent import HarnessAgentManager, HarnessAgentConfig, ProviderConfig
+
+manager = HarnessAgentManager()
+
+# Register agents with metadata and tags
+entry = manager.create_agent(
+    config,
+    metadata={"tenant": "acme", "env": "prod"},
+    tags=["fast", "gpt4o"],
+)
+
+# Query agents by metadata / tags
+agents = manager.list_agents(metadata={"env": "prod"}, tags=["fast"])
+
+# Stream by agent_id
+async for chunk in manager.stream(entry.agent_id, request):
+    print(chunk)
+
+# Cancel mid-stream
+manager.cancel(entry.agent_id, request.thread_id)
+```
+
+---
+
+## Architecture
+
+```
+src/harness_agent/          Core SDK — agent runtime, model routing, tools, skills, backends
+src/harness_agent/cli/      Terminal CLI — thin view layer over the SDK
+```
+
+The CLI is a thin view layer that delegates all agent logic to the core SDK. This separation enables future UIs (web, IDE extensions) to reuse the same SDK.
+
+---
+
+## Development
+
+**Prerequisites:** Python 3.11+, [uv](https://docs.astral.sh/uv/)
+
+```bash
+git clone https://github.com/orcakit/harness-agent.git
+cd harness-agent
+make install          # install dev dependencies
+make all              # lint + typecheck + test (CI ship bar)
+```
+
+| Command | Description |
+|---------|-------------|
+| `make lint` | Ruff check + format check |
+| `make format` | Auto-fix and format |
+| `make typecheck` | mypy strict |
+| `make test` | pytest with coverage |
+| `make build` | Build wheel + sdist |
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and run `make all` before opening a PR.
+
+Security issues: see [SECURITY.md](SECURITY.md).
+
+---
+
+## Release
+
+Tag `v<version>` (e.g., `v0.2.0`) to trigger a PyPI release via GitHub Actions with trusted publishing.
+
+---
+
+## Related Projects
+
+| Project | Description |
+|---------|-------------|
+| [orca (Octop)](https://github.com/orcakit/orca) | Self-hosted multi-user AI control plane |
+| [harness-memory](https://github.com/orcakit/harness-memory) | Pluggable memory system with hierarchical recall and FTS |
+| [harness-browser](https://github.com/orcakit/harness-browser) | AI-friendly browser automation via CDP |
+| [harness-gateway](https://github.com/orcakit/harness-gateway) | Multi-platform IM channel bridge for AI agents |
+
+---
+
+## License
+
+[MIT](LICENSE)