cube-agent-harness 0.1.0__py3-none-any.whl

cube/README.md

@@ -0,0 +1,369 @@
+# Cube SDK
+
+`cube` 是 `cube-agent-harness` 发行包安装后的 Python import 包：
+
+```bash
+pip install cube-agent-harness
+```
+
+```python
+import cube
+```
+
+Cube 是一个用于构建可嵌入、可使用工具、可通过插件扩展的 Agent Harness
+Python SDK。它拆成一个轻量 runtime kernel、可选的本地应用宿主、可选的分布式
+runtime，以及官方能力插件。
+
+## 包结构
+
+| 包 | 适用场景 | 主要入口 |
+| --- | --- | --- |
+| `cube.core` | 需要不依赖 platform 的 Agent runtime kernel。 | `AgentRuntime`, `AgentRunRequest`, `ToolRuntime`, `HookRuntime`, LLM/MCP contracts |
+| `cube.platform` | 需要本地可嵌入 Cube 应用，包含 SQLite、sessions、workspaces、plugins 和本地 runtime 激活。 | `CubeLocalApp`, `CubeLocalAppConfig`, `create_cube_local_app`, `PlatformServices`, `PlatformRuntime` |
+| `cube.cluster` | 需要基于 MySQL、Redis 和共享 workspace 的 Backend/Worker 分布式部署。 | `ClusterGateway`, `ClusterGatewayConfig`, `ClusterPlatformServicesConfig`, `ClusterWorker`, `ClusterWorkerConfig` |
+| `cube.plugins` | 需要官方具体 tools、hooks 和 session kinds。 | plugin entry points, bundled tools, chat/task/subagent sessions |
+
+独立 CLI 应用通过 `cube-cli` 单独发布，并安装 `cube` 命令。Playground 应用也不属于
+SDK wheel。
+
+## 安装配置
+
+基础安装保持轻量：
+
+```bash
+pip install cube-agent-harness
+```
+
+按需安装可选能力：
+
+```bash
+pip install "cube-agent-harness[llm]"       # LiteLLM client/router 支持
+pip install "cube-agent-harness[mcp]"       # MCP client 支持
+pip install "cube-agent-harness[platform]"  # 本地 platform host 和 SQLite
+pip install "cube-agent-harness[cluster]"   # 分布式 runtime：MySQL + Redis
+pip install "cube-agent-harness[all]"       # 全部官方 SDK extras
+```
+
+## 应该使用哪个入口？
+
+本地嵌入使用 `cube.platform.CubeLocalApp`：
+
+```python
+from cube.platform import CubeLocalAppConfig, create_cube_local_app
+
+app = create_cube_local_app(CubeLocalAppConfig.from_root_dir("./cube-data"))
+
+async with app.lifespan():
+    services = app.services
+    commands = app.commands
+    events = app.events
+```
+
+分布式 Backend 进程中，显式组合 durable services 和 live Gateway：
+
+```python
+from pathlib import Path
+
+from cube.cluster import (
+    ClusterConfig,
+    ClusterGateway,
+    ClusterGatewayConfig,
+    ClusterPlatformServicesConfig,
+    GatewayConfig,
+    MySQLConfig,
+    RedisConfig,
+    create_cluster_platform_services,
+)
+from cube.platform import RuntimeAssemblyConfig
+
+assembly = RuntimeAssemblyConfig(rollout_tag="v1")
+services = create_cluster_platform_services(
+    ClusterPlatformServicesConfig(
+        root_dir=Path("/cube"),
+        assembly=assembly,
+        mysql=MySQLConfig(
+            url="mysql+asyncmy://cube:secret@mysql:3306/cube?charset=utf8mb4",
+        ),
+    )
+)
+gateway = ClusterGateway(
+    config=ClusterGatewayConfig(
+        assembly=assembly,
+        cluster=ClusterConfig(namespace="cube-prod"),
+        redis=RedisConfig(url="redis://:secret@redis:6379/0"),
+        gateway=GatewayConfig(),
+    )
+)
+
+await services.startup()
+await gateway.startup()
+commands = gateway
+events = gateway
+```
+
+分布式 Worker 进程使用 `cube.cluster.ClusterWorker`：
+
+```bash
+CUBE_ROOT_DIR=/cube \
+CUBE_CLUSTER_NAMESPACE=cube-prod \
+CUBE_ROLLOUT_TAG=v1 \
+CUBE_MYSQL_URL='mysql+asyncmy://cube:secret@mysql:3306/cube?charset=utf8mb4' \
+CUBE_REDIS_URL='redis://:secret@redis:6379/0' \
+CUBE_WORKER_ID=worker-1 \
+python -m cube.cluster.worker
+```
+
+只有当你希望自己完整负责 persistence、session 语义、workspace 布局和 UI projection
+时，才直接使用 `cube.core.AgentRuntime`。
+
+## 统一应用接入面
+
+本地和分布式 composition 都应该向业务代码暴露同一组高层应用接入面：
+
+- `services`：durable agency/channel/session/workspace/database services。
+- `commands`：与 transport 无关的 live session command dispatcher。
+- `events`：按 session 订阅的 live event subscriber。
+
+这样 application services 可以依赖稳定协议，而不是依赖具体的本地 runtime 或 cluster
+gateway 类。
+
+应用后端通常应该在自己的 composition root 中隐藏部署形态选择：
+
+```python
+from dataclasses import dataclass
+
+from cube.platform import PlatformServices
+from cube.platform.command import SessionCommandDispatcher
+from cube.platform.event import SessionEventSubscriber
+
+
+@dataclass(frozen=True)
+class CubeComponents:
+    services: PlatformServices
+    commands: SessionCommandDispatcher
+    events: SessionEventSubscriber
+```
+
+本地 backend composition 从 `CubeLocalApp` 填充这些字段：
+
+```python
+from cube.platform import CubeLocalAppConfig, create_cube_local_app
+
+
+cube_app = create_cube_local_app(
+    CubeLocalAppConfig.from_root_dir("./cube-data"),
+)
+cube = CubeComponents(
+    services=cube_app.services,
+    commands=cube_app.commands,
+    events=cube_app.events,
+)
+```
+
+分布式 backend composition 从 distributed services 和 Gateway 填充同样的字段：
+
+```python
+services = create_cluster_platform_services(...)
+gateway = ClusterGateway(...)
+cube = CubeComponents(
+    services=services,
+    commands=gateway,
+    events=gateway,
+)
+```
+
+Route handlers 和 application services 应该按职责使用这些字段：
+
+```python
+# Durable 查询和管理不会激活 live sessions。
+channel = await cube.services.channels.get(agency_code, channel_code)
+history = await cube.services.sessions.get_history(address.session_id)
+
+# Live commands 通过 transport-neutral command boundary。
+result = await cube.commands.dispatch(command)
+
+# Live UI 更新通过 event boundary 订阅。
+async with cube.events.subscribe(address) as stream:
+    async for event in stream:
+        ...
+```
+
+分布式模式下，Backend 禁止创建 `PlatformRuntime`，也禁止在同一进程内启动 Worker。
+Worker 是独立的 `ClusterWorker` 进程。
+
+## Runtime Assembly
+
+Cube 从 runtime-local manifests 加载 plugins 和 tables：
+
+```text
+<root_dir>/plugins.toml
+<root_dir>/tables.toml
+```
+
+`RuntimeAssembly` 会在注入 `PlatformServices` 前冻结已选择的 plugin registry、table
+registry 和 capability assembly。
+
+应用拥有自己的默认 manifests。SDK 不会自动 import 所有已安装 plugins，也不会自动
+import 所有 table modules。
+
+## 插件扩展
+
+插件通过 `cube.plugins` entry point group 暴露 `PluginSpec`：
+
+```python
+from cube.platform.plugin import PluginSpec
+
+
+def register(ctx):
+    ctx.tools("my_tools", my_tool)
+
+
+plugin = PluginSpec(
+    name="my.company.plugin",
+    version="0.1.0",
+    register=register,
+)
+```
+
+```toml
+[project.entry-points."cube.plugins"]
+"my.company.plugin" = "my_company.plugin:plugin"
+```
+
+插件可以贡献 tools、hooks、hook event contracts 和 session kinds。带持久化能力的
+plugins 需要单独声明 `TableSpec` 对象，并在 `PluginSpec.requires_tables` 中列出
+所需的逻辑 table names。
+
+## 本地模式与分布式模式
+
+本地模式：
+
+- 使用 `cube.platform.CubeLocalApp`
+- 使用 SQLite 和本地 POSIX workspace
+- 在应用进程内激活 sessions
+- 使用进程内 event delivery
+
+分布式模式：
+
+- Backend 进程使用 `cube.cluster.ClusterGateway`
+- Worker 进程使用 `cube.cluster.ClusterWorker`
+- 使用 MySQL 存储 Cube durable domain data
+- 使用 Redis 承载 worker heartbeat、owner leases、command ACKs 和 live events
+- 要求所有节点可见同一个共享 POSIX workspace
+
+分布式模式有意不提供 `CubeApp` facade。本地嵌入仍然使用
+`cube.platform.CubeLocalApp`；分布式 Backend composition 直接连接
+`PlatformServices` 和 `ClusterGateway`。
+
+## 本地快捷调试：分布式模式
+
+在 Cube 源码仓库中开发 Playground、`cube.cluster`、Worker、tools 或 sessions
+时，推荐使用根目录 `Makefile` 提供的本地多进程模式。它不使用 Docker 包住源码，
+但运行拓扑仍然是完整的分布式模式：
+
+```text
+Next.js frontend :3000
+        |
+distributed Playground backend :8000
+        |
+ClusterGateway -- Redis -- ClusterWorker(s)
+        |                       |
+        +------ MySQL ----------+
+        +--- shared root_dir ---+
+```
+
+### macOS 一次性准备
+
+本机需要 Git、Make、`uv`、npm，以及 Node.js 20.11 或更高版本；推荐与官方
+Worker 镜像一致使用 Node.js 22。Python 3.12/3.13 和项目 Python 依赖由 `uv`
+根据 workspace 配置准备。
+
+把部署配置放在仓库根目录 `.env`。最少需要正确配置：
+
+```text
+CUBE_ROOT_DIR
+CUBE_CLUSTER_NAMESPACE
+CUBE_ROLLOUT_TAG
+CUBE_MYSQL_URL
+CUBE_REDIS_URL
+PLAYGROUND_DATABASE_URL
+PLAYGROUND_AUTH_SECRET
+```
+
+`CUBE_MYSQL_URL` 使用 Cube runtime 数据库；`PLAYGROUND_DATABASE_URL` 使用
+Playground 自己的 account 数据库。两个 database 需要提前存在并允许对应账号建表。
+本机单套 backend/worker 可以共用一个本地可写的 `CUBE_ROOT_DIR`；跨机器运行时，
+所有 backend/worker 必须看到同一个共享 POSIX/NAS 路径。
+
+每位开发者应使用独立的 cluster namespace、worker-id prefix、Cube database、
+Playground database 和本地 root directory。只共享 MySQL/Redis、却各用一份本地
+workspace，会让不同 Worker 看到同一批 sessions 但看到不同文件，不是有效拓扑。
+
+### 标准 Make 流程
+
+首次拿到代码和 `.env` 后：
+
+```bash
+make doctor
+make local-start
+```
+
+`make doctor` 只读检查 macOS host tools、Node.js 版本、root directory 权限，
+以及 MySQL、Redis、Playground database 连通性，不创建表。`make local-start`
+随后会依次：
+
+1. 在 `deploy/local/sandbox-tools/` 安装或校验固定版本的 SRT 和 ripgrep；不安装
+   全局 npm 包，macOS 也不需要手工安装 Linux 的 `bubblewrap`/`socat`。
+2. 保留已有 `plugins.toml` / `tables.toml`，缺失时写入 Playground defaults。
+3. 创建并校验 Cube MySQL tables。
+4. 启动默认两个 `ClusterWorker`，等待它们在 Redis 发布匹配 namespace/rollout 的
+   heartbeat。
+5. 启动 distributed Playground backend 并等待 HTTP readiness。
+6. 启动带热更新的 Next.js frontend 并等待 `http://localhost:3000` 可访问。
+
+日常命令：
+
+```bash
+make local-status
+make local-logs
+make local-restart   # 修改 Worker/cube runtime 代码后使用
+make local-shutdown
+```
+
+backend 和 frontend 启用源码热更新；Worker/runtime 代码变更需要
+`make local-restart`。启动任一环节 readiness 失败时，launcher 会输出相关日志、
+停止已记录的本地进程并以失败状态退出。
+
+常用覆盖参数：
+
+```bash
+make doctor ENV_FILE=config/alice.env
+make local-start ENV_FILE=config/alice.env LOCAL_WORKERS=1
+make local-start LOCAL_CLUSTER_READY_TIMEOUT_SECONDS=120
+make local-prepare LOCAL_OVERWRITE_MANIFESTS=1
+```
+
+`make local-prepare` 只用于“初始化但不启动”；它不是 `local-start` 的必需前置。
+`LOCAL_OVERWRITE_MANIFESTS=1` 会有意覆盖已有 runtime manifests，应只在需要恢复
+当前 Playground defaults 时使用。
+
+如果目标是验证镜像而不是源码热调试，使用：
+
+```bash
+make docker-build
+make docker-up
+make docker-down
+```
+
+Docker Compose 会把源码和依赖构建进镜像、把 frontend 导出为静态资源，不挂载
+源码，也不提供本地热更新。完整环境变量、sandbox policy、日志位置和故障处理见
+仓库根目录 `deploy/README.md`。
+
+## 更多文档
+
+- `cube/core/README.md`：core runtime、tools、hooks、LLM、MCP。
+- `cube/platform/README.md`：local app host、durable services、session command
+  和 event protocols。
+- `cube/cluster/README.md`：distributed Backend/Worker runtime。
+- `cube/platform/plugin/README.md`：plugin SPI 和 registration model。
+- `cube/plugins/README.md`：官方 bundled plugin implementations。

cube/__init__.py

@@ -0,0 +1 @@
+"""Cube package."""

cube/_optional.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+
+def import_optional_dependency(module_name: str, *, extra: str, feature: str) -> Any:
+    try:
+        return importlib.import_module(module_name)
+    except ImportError as error:
+        raise RuntimeError(
+            f"{feature} requires optional dependency {module_name!r}. "
+            f"Install Cube with the '{extra}' extra."
+        ) from error
+
+
+__all__ = ["import_optional_dependency"]

cube/cluster/README.md

@@ -0,0 +1,277 @@
+# cube.cluster
+
+`cube.cluster` is Cube's distributed runtime SDK surface. It adds the minimum
+coordination layer needed to run Cube sessions across multiple application
+backend and worker processes.
+
+The package is intentionally separate from `cube.platform`:
+
+- `cube.platform` owns the local app host and durable platform services.
+- `cube.cluster` owns Redis/MySQL-backed distributed command routing, owner
+  leases, worker heartbeat, and live event forwarding.
+- `cube.plugins` still owns concrete tools, hooks, and session kinds.
+
+Install with the `cluster` extra:
+
+```bash
+pip install "cube-agent-harness[cluster]"
+```
+
+In this repository use:
+
+```bash
+uv sync --all-packages --all-extras
+```
+
+## Runtime Shape
+
+Distributed mode has two process roles.
+
+| Role | SDK entry | Owns | Does not own |
+| --- | --- | --- | --- |
+| Backend / Gateway | `PlatformServices` + `cube.cluster.ClusterGateway` | durable services, command dispatch, event subscription | `PlatformRuntime`, live Session execution |
+| Worker | `cube.cluster.ClusterWorker` | `PlatformServices`, `PlatformRuntime`, owner leases, command handling, event forwarding | HTTP routes, accounts, frontend projection |
+
+The backend receives application HTTP/WebSocket traffic, performs durable reads,
+and submits live commands through `ClusterGateway`. Workers claim session owner
+leases and execute the actual `PlatformRuntime` work.
+
+There is intentionally no distributed `CubeApp` facade. Local embedding still
+uses `cube.platform.CubeLocalApp`; distributed Backend applications compose
+`PlatformServices` and `ClusterGateway` directly.
+
+## Public API
+
+Top-level exports:
+
+```python
+from cube.cluster import (
+    CLUSTER_PROTOCOL_VERSION,
+    ClusterConfig,
+    ClusterGateway,
+    ClusterGatewayConfig,
+    ClusterPlatformServicesConfig,
+    ClusterWorker,
+    ClusterWorkerConfig,
+    GatewayConfig,
+    MySQLConfig,
+    RedisConfig,
+    WorkerConfig,
+    create_cluster_platform_services,
+    init_cluster_schema,
+    validate_cluster_schema,
+)
+```
+
+Important config objects:
+
+- `ClusterConfig`: shared coordination namespace used in Redis key prefixes and
+  envelopes.
+- `ClusterPlatformServicesConfig`: Backend/Worker durable service config for
+  MySQL, shared root directory, and runtime assembly.
+- `ClusterGatewayConfig`: Backend-side Gateway config for cluster namespace,
+  Redis, rollout tag, request limits, and command timeout.
+- `ClusterWorkerConfig`: worker-side config for `ClusterWorker`.
+- `GatewayConfig`: request timeout, pending request limit, optional gateway id,
+  and optional worker active-session capacity filter.
+- `WorkerConfig`: optional worker id, heartbeat interval/TTL, owner lease TTL,
+  request ACK TTL, dependency grace, and shutdown grace.
+- `MySQLConfig`: SQLAlchemy async MySQL URL and pool settings.
+- `RedisConfig`: Redis URL and socket timeout settings.
+
+## Backend Usage
+
+Backend applications usually compose durable services and Gateway at their
+composition root.
+
+```python
+from pathlib import Path
+
+from cube.cluster import (
+    ClusterConfig,
+    ClusterGateway,
+    ClusterGatewayConfig,
+    ClusterPlatformServicesConfig,
+    GatewayConfig,
+    MySQLConfig,
+    RedisConfig,
+    create_cluster_platform_services,
+)
+from cube.platform import RuntimeAssemblyConfig
+
+assembly = RuntimeAssemblyConfig(rollout_tag="v1")
+services = create_cluster_platform_services(
+    ClusterPlatformServicesConfig(
+        root_dir=Path("/cube"),
+        assembly=assembly,
+        mysql=MySQLConfig(
+            url="mysql+asyncmy://cube:secret@mysql:3306/cube?charset=utf8mb4",
+        ),
+    )
+)
+gateway = ClusterGateway(
+    config=ClusterGatewayConfig(
+        assembly=assembly,
+        cluster=ClusterConfig(namespace="cube-prod"),
+        redis=RedisConfig(url="redis://:secret@redis:6379/0"),
+        gateway=GatewayConfig(command_timeout_seconds=30),
+    )
+)
+
+await services.startup()
+await gateway.startup()
+commands = gateway
+events = gateway
+```
+
+Use the surfaces by responsibility:
+
+- Durable reads and management go through `app.services`.
+- Live session commands go through `app.commands.dispatch(...)`.
+- Live session events go through `app.events.subscribe(...)`.
+
+Backend code must not create `PlatformRuntime` in distributed mode.
+
+## Worker Usage
+
+Workers can be constructed directly:
+
+```python
+from pathlib import Path
+
+from cube.cluster import (
+    ClusterConfig,
+    ClusterWorker,
+    ClusterWorkerConfig,
+    MySQLConfig,
+    RedisConfig,
+    WorkerConfig,
+)
+from cube.platform import RuntimeAssemblyConfig
+
+worker = ClusterWorker(
+    config=ClusterWorkerConfig(
+        root_dir=Path("/cube"),
+        assembly=RuntimeAssemblyConfig(rollout_tag="v1"),
+        cluster=ClusterConfig(namespace="cube-prod"),
+        mysql=MySQLConfig(
+            url="mysql+asyncmy://cube:secret@mysql:3306/cube?charset=utf8mb4",
+        ),
+        redis=RedisConfig(url="redis://:secret@redis:6379/0"),
+        worker=WorkerConfig(worker_id="worker-1"),
+    )
+)
+
+async with worker.lifespan():
+    await worker.run()
+```
+
+The built-in worker entrypoint reads environment variables:
+
+```bash
+CUBE_ROOT_DIR=/cube \
+CUBE_CLUSTER_NAMESPACE=cube-prod \
+CUBE_ROLLOUT_TAG=v1 \
+CUBE_MYSQL_URL='mysql+asyncmy://cube:secret@mysql:3306/cube?charset=utf8mb4' \
+CUBE_REDIS_URL='redis://:secret@redis:6379/0' \
+CUBE_WORKER_ID=worker-1 \
+python -m cube.cluster.worker
+```
+
+`CUBE_WORKER_ID` is optional. If omitted, the SDK generates a process-local
+worker id.
+
+## Schema Lifecycle
+
+Distributed runtime uses MySQL for Cube durable domain tables. For production,
+DDL is usually owned by deployment or database operations. For a first test
+deployment, the SDK exposes explicit helpers:
+
+```python
+await init_cluster_schema(config)
+await validate_cluster_schema(config)
+```
+
+`init_cluster_schema(...)` creates the tables selected by the current
+`tables.toml`. `validate_cluster_schema(...)` checks compatibility without
+running DDL. Runtime startup validates schema but does not automatically create
+or migrate tables.
+
+## Required Runtime Files
+
+Both backend and worker processes must see the same runtime assembly files under
+`<root_dir>/`:
+
+```text
+<root_dir>/plugins.toml
+<root_dir>/tables.toml
+```
+
+The selected plugins, tables, package version, and `rollout_tag` should match
+between backends and workers.
+
+`root_dir` must be shared across nodes in distributed mode. For multi-ECS
+deployments this should be a shared POSIX mount such as NAS, not a local
+disk path that differs by machine.
+
+## Command And Event Flow
+
+The core live path is:
+
+```text
+Backend
+-> ClusterGateway
+-> Redis Pub/Sub command request
+-> ClusterWorker
+-> owner lease claim or owner verification
+-> PlatformRuntime / Session
+-> durable state in MySQL and shared workspace
+-> Redis Pub/Sub live event
+-> Backend event subscription
+```
+
+`CommandStatus.TIMEOUT` means the Gateway did not receive a worker ACK before
+the request deadline. It does not prove the worker did not execute the request.
+V1 does not automatically replay timed-out commands.
+
+## Health
+
+Backend applications can combine `services.health()` and `gateway.health()` for
+readiness. `ClusterWorker.health()` reports platform service health plus Redis
+heartbeat and command subscriber state.
+
+Health snapshots are for readiness/diagnostics. They are not a scheduler or
+durable recovery mechanism.
+
+## Playground Integration
+
+The Playground backend supports distributed mode through environment variables:
+
+```bash
+PLAYGROUND_RUNTIME_PROFILE=distributed
+CUBE_ROOT_DIR=/cube
+CUBE_CLUSTER_NAMESPACE=cube-prod
+CUBE_ROLLOUT_TAG=v1
+CUBE_MYSQL_URL='mysql+asyncmy://cube:secret@mysql:3306/cube?charset=utf8mb4'
+CUBE_REDIS_URL='redis://:secret@redis:6379/0'
+PLAYGROUND_AUTH_SECRET='at-least-32-random-characters'
+```
+
+When this profile is selected, the backend creates distributed `PlatformServices`
+and a `ClusterGateway`, then exposes `services`, `commands`, and `events` to
+application routes. Worker processes still run separately.
+
+## V1 Boundaries
+
+The current V1 skeleton intentionally keeps recovery small:
+
+- No Redis Streams/List durable command queue.
+- No transactional outbox or event replay.
+- No automatic retry/reconciliation for timed-out commands.
+- No distributed `WarmupSession`; it is rejected in distributed mode.
+- No local fallback when Redis/MySQL/shared workspace is unavailable.
+- No Session-to-Session routing or mailbox.
+
+Frontend or application users should handle clear failures by retrying or
+starting a new request. Durable state remains in MySQL and the shared workspace;
+live events are best effort.