CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
refactor(compat): replace cubepi shim with tombstone
xf gongdb60cb9d635b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex da7237b..358e819 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,23 +14,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- **The CubeLoop rename no longer renames the persistent Postgres/MySQLschema.** Physical tables, partitions, indexes, and the version marker remain`cubepi_*` at schema version 5, so an existing 0.13.6 database opens without- DDL and historical host Alembic revisions remain reproducible. The withdrawn- 0.14.0 release briefly used `cubeloop_*`; see the migration guide for the- exceptional recovery procedure.-- **The transitional `cubepi` package accepts compatible 0.14 patch releases.**- Its dependency and forwarded extras now use `cubeloop>=0.14.1,<0.15`.--## [0.14.0] - 2026-09-10 [YANKED]--### Breaking--- **Renamed CubePi / `cubepi` to CubeLoop / `cubeloop`.** The import path,- PyPI project, CLI, docs site (`https://cubeloop.dev`), OTel vendor- namespace (`cubeloop.*`), and — incorrectly — Postgres/MySQL table names- (`cubeloop_*`) all moved. This release was withdrawn because the database- rename broke reproducible host Alembic histories and safe rollback. Use- 0.14.1 or later. See the- [migration guide](https://cubeloop.dev/docs/migration/from-cubepi).+ DDL and historical host Alembic revisions remain reproducible.+- **The `cubepi` package is now a fail-fast tombstone.** It has no dependencies,+ exports, import aliases, or CLI proxy. Imports and commands fail with explicit+ instructions to install and migrate to `cubeloop`.## [0.13.6] - 2026-09-04@@ -825,8 +812,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- **[0.1.0]** - 2026-05-09 — initial release. See the [release notes](https://github.com/cubeplexai/cubepi/releases/tag/v0.1.0).[Unreleased]: https://github.com/cubeplexai/cubeloop/compare/v0.14.1...HEAD-[0.14.1]: https://github.com/cubeplexai/cubeloop/compare/v0.14.0...v0.14.1-[0.14.0]: https://github.com/cubeplexai/cubeloop/compare/v0.13.6...v0.14.0+[0.14.1]: https://github.com/cubeplexai/cubeloop/compare/v0.13.6...v0.14.1[0.13.6]: https://github.com/cubeplexai/cubeloop/compare/v0.13.5...v0.13.6[0.13.5]: https://github.com/cubeplexai/cubeloop/compare/v0.13.4...v0.13.5[0.13.4]: https://github.com/cubeplexai/cubeloop/compare/v0.13.3...v0.13.4diff --git a/compat/cubepi/README.md b/compat/cubepi/README.mdindex e247b4f..e52103f 100644--- a/compat/cubepi/README.md+++ b/compat/cubepi/README.md@@ -10,9 +10,8 @@ pip install cubeloopfrom cubeloop import Agent, tool```-This distribution is a transitional wrapper: it depends on a compatible-`cubeloop>=0.14.1,<0.15`,-re-exports the public API, and aliases `cubepi.*` imports onto `cubeloop.*`.-Installing it prints a deprecation warning on first import.+This distribution is a dependency-free tombstone. It does not install, import,+or proxy CubeLoop. Any `cubepi` import or command fails with migration+instructions so stale dependencies cannot silently continue.See https://cubeloop.dev/docs/migration/from-cubepidiff --git a/compat/cubepi/cubepi/__init__.py b/compat/cubepi/cubepi/__init__.pyindex 39a857e..0518cfa 100644--- a/compat/cubepi/cubepi/__init__.py+++ b/compat/cubepi/cubepi/__init__.py@@ -1,31 +1,7 @@-"""Transitional alias for the renamed cubeloop package."""+"""Removed package name; use :mod:`cubeloop` instead."""-from __future__ import annotations--import sys-import warnings--from cubepi._redirect import install as _install_redirect--_WARNING = (- "WARNING: The 'cubepi' package has been renamed to 'cubeloop'.\n"- "Install `cubeloop` and import from `cubeloop` instead.\n"- "See https://cubeloop.dev/docs/migration/from-cubepi\n"+raise ImportError(+ "The 'cubepi' package has been renamed and no longer provides an API. "+ "Install 'cubeloop' and replace 'cubepi' imports with 'cubeloop'. "+ "See https://cubeloop.dev/docs/migration/from-cubepi")--_install_redirect()--if not getattr(sys, "_cubepi_rename_warned", False):- sys._cubepi_rename_warned = True # type: ignore[attr-defined]- warnings.warn(- "The 'cubepi' package has been renamed to 'cubeloop'. "- "Install `cubeloop` and import from `cubeloop` instead. "- "See https://cubeloop.dev/docs/migration/from-cubepi",- DeprecationWarning,- stacklevel=2,- )- print(_WARNING, file=sys.stderr, end="")--from cubeloop import * # noqa: E402,F403-from cubeloop import __all__ as __all__ # noqa: E402-from cubeloop import __version__ as __version__ # noqa: E402diff --git a/compat/cubepi/cubepi/__main__.py b/compat/cubepi/cubepi/__main__.pydeleted file mode 100644index 9d3ba2d..0000000--- a/compat/cubepi/cubepi/__main__.py+++ /dev/null@@ -1,23 +0,0 @@-"""`cubepi` console script — warn, then dispatch to cubeloop.cli."""--from __future__ import annotations--import sys-from collections.abc import Sequence--_WARNING = (- "WARNING: The 'cubepi' package has been renamed to 'cubeloop'.\n"- "Install `cubeloop` and import from `cubeloop` instead.\n"- "See https://cubeloop.dev/docs/migration/from-cubepi\n"-)---def main(argv: Sequence[str] | None = None) -> int:- print(_WARNING, file=sys.stderr, end="")- from cubeloop.cli.__main__ import main as _real-- return _real(argv)---if __name__ == "__main__":- sys.exit(main())diff --git a/compat/cubepi/cubepi/_redirect.py b/compat/cubepi/cubepi/_redirect.pydeleted file mode 100644index 7b70121..0000000--- a/compat/cubepi/cubepi/_redirect.py+++ /dev/null@@ -1,61 +0,0 @@-"""On-demand cubepi.* → cubeloop.* import alias."""--from __future__ import annotations--import importlib-import importlib.abc-import importlib.machinery-import importlib.util-import sys---class _AliasLoader(importlib.abc.Loader):- def __init__(self, real_name: str) -> None:- self.real_name = real_name-- def create_module(self, spec: importlib.machinery.ModuleSpec): # noqa: ARG002- return importlib.import_module(self.real_name)-- def exec_module(self, module: object) -> None: # noqa: ARG002- return None-- def get_code(self, fullname: str): # noqa: ARG002- # runpy (`python -m cubepi.cli`) requires get_code; delegate to- # cubeloop's real loader so aliased packages stay executable.- spec = importlib.util.find_spec(self.real_name)- if spec is None or spec.loader is None:- return None- getter = getattr(spec.loader, "get_code", None)- if getter is None:- return None- return getter(self.real_name)---class CubepiRedirectFinder(importlib.abc.MetaPathFinder):- """Resolve cubepi.foo to the already-named cubeloop.foo module object."""-- def find_spec( # type: ignore[override]- self,- fullname: str,- path: object, # noqa: ARG002- target: object = None, # noqa: ARG002- ) -> importlib.machinery.ModuleSpec | None:- if not fullname.startswith("cubepi."):- return None- real_name = "cubeloop" + fullname[len("cubepi") :]- real_spec = importlib.util.find_spec(real_name)- if real_spec is None:- return None- spec = importlib.machinery.ModuleSpec(- fullname,- _AliasLoader(real_name),- origin=real_spec.origin,- is_package=real_spec.submodule_search_locations is not None,- )- spec.submodule_search_locations = real_spec.submodule_search_locations- return spec---def install() -> None:- if not any(isinstance(f, CubepiRedirectFinder) for f in sys.meta_path):- sys.meta_path.insert(0, CubepiRedirectFinder())diff --git a/compat/cubepi/pyproject.toml b/compat/cubepi/pyproject.tomlindex cc57425..43e91e5 100644--- a/compat/cubepi/pyproject.toml+++ b/compat/cubepi/pyproject.toml@@ -1,7 +1,7 @@[project]name = "cubepi"version = "0.14.1"-description = "DEPRECATED: Cubepi has been renamed to cubeloop. This package is a transitional wrapper."+description = "REMOVED: Install cubeloop and migrate imports from cubepi."readme = "README.md"license = "MIT"requires-python = ">=3.11"@@ -12,18 +12,7 @@ classifiers = ["Programming Language :: Python :: 3.13","Programming Language :: Python :: 3.14",]-dependencies = [- "cubeloop>=0.14.1,<0.15",-]--[project.optional-dependencies]-sqlite = ["cubeloop[sqlite]>=0.14.1,<0.15"]-postgres = ["cubeloop[postgres]>=0.14.1,<0.15"]-mysql = ["cubeloop[mysql]>=0.14.1,<0.15"]-mcp = ["cubeloop[mcp]>=0.14.1,<0.15"]-tracing = ["cubeloop[tracing]>=0.14.1,<0.15"]-tracing-otlp = ["cubeloop[tracing-otlp]>=0.14.1,<0.15"]-trace-cli = ["cubeloop[trace-cli]>=0.14.1,<0.15"]+dependencies = [][project.scripts]cubepi = "cubepi.__main__:main"@@ -38,6 +27,3 @@ build-backend = "hatchling.build"[tool.hatch.build.targets.wheel]packages = ["cubepi"]--[tool.uv.sources]-cubeloop = { workspace = true }diff --git a/cubeloop/checkpointer/mysql/checkpointer.py b/cubeloop/checkpointer/mysql/checkpointer.pyindex 17a537f..9ea5017 100644--- a/cubeloop/checkpointer/mysql/checkpointer.py+++ b/cubeloop/checkpointer/mysql/checkpointer.py@@ -189,14 +189,7 @@ class MySQLCheckpointer:raise CubeloopSchemaMismatch(expected=EXPECTED_SCHEMA_VERSION,actual=actual,- hint=(- "database schema is newer than this CubeLoop "- "release. If withdrawn 0.14.0 wrote version 6, "- "inspect the database and follow "- "https://cubeloop.dev/docs/migration/"- "from-cubepi#emergency-recovery-from-withdrawn-0140; "- "do not run a forward migration."- ),+ hint="database schema is newer than this CubeLoop release.",)steps = ", ".join(f"upgrade_v{v}_to_v{v + 1}_op()"@@ -216,27 +209,10 @@ class MySQLCheckpointer:)return- withdrawn, withdrawn_missing = await self._select_version(- cur, "cubeloop_schema_version"- )- if not withdrawn_missing and withdrawn is not None:- actual = int(withdrawn[0])- raise CubeloopSchemaMismatch(- expected=EXPECTED_SCHEMA_VERSION,- actual=actual,- hint=(- "database uses the withdrawn 0.14.0 cubeloop_* "- "schema. Inspect it and follow "- "https://cubeloop.dev/docs/migration/"- "from-cubepi#emergency-recovery-from-withdrawn-0140; "- "do not run a forward migration."- ),- )-await cur.execute("SELECT COUNT(*) FROM information_schema.tables ""WHERE table_schema = DATABASE() "- "AND table_name IN ('cubepi_threads', 'cubeloop_threads')"+ "AND table_name = 'cubepi_threads'")count_row = await cur.fetchone()if count_row and count_row[0]:diff --git a/cubeloop/checkpointer/postgres/checkpointer.py b/cubeloop/checkpointer/postgres/checkpointer.pyindex 0e2d0b2..dd1add1 100644--- a/cubeloop/checkpointer/postgres/checkpointer.py+++ b/cubeloop/checkpointer/postgres/checkpointer.py@@ -53,12 +53,7 @@ def _schema_mismatch_hint(actual: int, expected: int) -> str:transition, so the hint stays correct as EXPECTED_SCHEMA_VERSION grows."""if actual > expected:- return (- "database schema is newer than this CubeLoop release. If withdrawn "- "0.14.0 wrote version 6, inspect the database and follow "- "https://cubeloop.dev/docs/migration/from-cubepi#emergency-recovery-"- "from-withdrawn-0140; do not run a forward migration."- )+ return "database schema is newer than this CubeLoop release."steps = ", ".join(f"upgrade_v{v}_to_v{v + 1}_op()" for v in range(actual, expected))return ("cubeloop was upgraded but host alembic is behind. "@@ -75,12 +70,6 @@ _MISSING_VERSION_TABLE_HINT = ("apply fresh CREATE TABLE statements on existing data.")-_WITHDRAWN_V6_HINT = (- "database uses the withdrawn 0.14.0 cubeloop_* schema. Inspect it and "- "follow https://cubeloop.dev/docs/migration/from-cubepi#emergency-recovery-"- "from-withdrawn-0140; do not run a forward migration."-)-def _serialize_structured_value(value: StructuredValue) -> str:return _STRUCTURED_VALUE_ADAPTER.dump_json(value).decode("utf-8")@@ -180,22 +169,8 @@ class PostgresCheckpointer:"SELECT version FROM cubepi_schema_version LIMIT 1")except asyncpg.UndefinedTableError:- try:- withdrawn = await conn.fetchrow(- "SELECT version FROM cubeloop_schema_version LIMIT 1"- )- except asyncpg.UndefinedTableError:- withdrawn = None- if withdrawn is not None:- actual = int(withdrawn["version"])- raise CubeloopSchemaMismatch(- expected=EXPECTED_SCHEMA_VERSION,- actual=actual,- hint=_WITHDRAWN_V6_HINT,- )has_data = await conn.fetchval(- "SELECT to_regclass('cubepi_threads') IS NOT NULL "- "OR to_regclass('cubeloop_threads') IS NOT NULL"+ "SELECT to_regclass('cubepi_threads') IS NOT NULL")if has_data:raise CubeloopSchemaMismatch(diff --git a/dev/plans/2026-09-10-retain-cubepi-schema.md b/dev/plans/2026-09-10-retain-cubepi-schema.mdindex c1fa372..eb7a1c0 100644--- a/dev/plans/2026-09-10-retain-cubepi-schema.md+++ b/dev/plans/2026-09-10-retain-cubepi-schema.md@@ -5,35 +5,27 @@**Worktree:** `.worktrees/2026-09-10-retain-cubepi-schema` on branch`2026-09-10-retain-cubepi-schema`.-## 1. Prepare withdrawal communication+## 1. Prepare deletion communication-- Prepare the public incident/recovery page and v0.14.0 release-note amendment.-- Do not yank until the recovery page is merged and deployed (or the release note- contains the complete recovery procedure inline).+- Update the migration page and v0.14.0 release notes to say 0.14.0 was removed+ and 0.14.1 is the first supported CubeLoop release.## 2. Restore the v5 persistence contract- Change Postgres/MySQL model table/index names back to `cubepi_*` while retaining`Cubeloop*` Python names and `cubeloop_metadata`.- Set both database `EXPECTED_SCHEMA_VERSION` constants to 5.-- Restore all runtime and verification SQL identifiers to `cubepi_*`; remove the- v6-specific diagnosis path.+- Restore all runtime and verification SQL identifiers to `cubepi_*`; remove all+ v6-specific diagnosis and recovery paths.- Restore Alembic helper SQL to the exact 0.13.6 storage semantics and remove`upgrade_v5_to_v6_op()`.- Restore examples and backend READMEs.-## 3. Create and test the recovery source+## 3. Remove the withdrawn recovery surface-- Add canonical machine-readable scripts at- `website/static/recovery/0.14.0/postgres-v6-to-v5.sql` and- `website/static/recovery/0.14.0/mysql-v6-to-v5.sql`. These are the only- executable recovery source; EN/zh-Hans docs link to the same downloads and- explain backup, stop-the-world, execution, and verification rather than- maintaining translated SQL copies.-- Each script performs collision/mixed-state preflight before mutation and- restores tables, Postgres partitions, indexes, and schema version 5.-- Test both scripts against an exact v6 fixture with data, indexes, constraints,- and partitions; prove preflight failure leaves mixed/colliding schemas intact.+- Delete the PostgreSQL/MySQL reverse-rename scripts and their integration tests.+- Delete runtime probes and special error messages for `cubeloop_*` database+ objects. Retain ordinary v5 version and missing-schema validation.## 4. Lock down migration reproducibility@@ -46,10 +38,13 @@## 5. Repair packaging and documentation-- Bump root and shim projects to 0.14.1 and change shim dependency/extras to- `>=0.14.1,<0.15`.+- Bump root and tombstone projects to 0.14.1. Remove all tombstone dependencies,+ extras forwarding, import aliases, API exports, and CLI dispatch.+- Test top-level/deep imports and both command forms for non-zero actionable+ failure without importing or installing `cubeloop`; Python tracebacks are+ acceptable as long as they contain the guidance.- Rewrite the current and version-0.14 migration/checkpoint docs in English and- zh-Hans; include isolated emergency reverse-rename instructions for 0.14.0.+ zh-Hans; remove every recovery link and state that 0.14.0 was deleted.- Correct the existing 0.14 pages in place; do not rerun docs version creation oralter versions/sidebars/latest-version state.- Update recipes, generated API references as required, changelog, and release@@ -72,13 +67,12 @@- Run spec → plan → code reviews with `codex:rescue`, fixing until clean.- Commit and push the branch; open the replacement PR with test evidence.- Run the PR Codex poll/fix/`@codex` loop until clean and wait for CI.-- Merge and wait for the recovery page and downloadable scripts to deploy.-- Amend the v0.14.0 GitHub release, yank both 0.14.0 PyPI projects with the- approved reason, verify their JSON metadata, and close #223 as superseded.+- Merge and wait for the migration page to deploy.- Verify the merged `main` commit already contains the reviewed 0.14.1 versionsand changelog from this PR. Explicitly skip `dev/runbooks/cut-doc-version.md`and never run `docusaurus docs:version 0.14`; the existing snapshot wascorrected in place.-- Tag that exact clean `main` commit as v0.14.1, publish both wheels, then verify- PyPI metadata and clean-machine installation of both `cubeloop==0.14.1` and- `cubepi==0.14.1`.+- Tag that exact clean `main` commit as v0.14.1, publish both wheels, and verify+ PyPI metadata and clean-machine behavior. In the same release window, delete+ both 0.14.0 PyPI releases and verify their files are gone. Then amend the+ v0.14.0 GitHub release and close #223 as superseded.diff --git a/dev/specs/2026-09-10-retain-cubepi-schema.md b/dev/specs/2026-09-10-retain-cubepi-schema.mdindex 034788f..09aebc4 100644--- a/dev/specs/2026-09-10-retain-cubepi-schema.md+++ b/dev/specs/2026-09-10-retain-cubepi-schema.md@@ -13,9 +13,10 @@| Product, package, imports, CLI | Remain CubeLoop / `cubeloop` || Postgres and MySQL physical names | Keep `cubepi_*` permanently || Schema version | Remain v5; the brand rename is not a schema change |-| 0.14.0 | Yank both PyPI distributions, without deleting files or the GitHub tag/release |-| Recovery scope | No runtime dual-schema support; document an emergency reverse rename for any early adopter |+| 0.14.0 | Delete both PyPI releases; keep the GitHub tag/release as incident history |+| Recovery scope | None; 0.14.0 had no users and is removed rather than supported || Replacement | Publish 0.14.1 after clean review and CI |+| `cubepi` package | Publish a dependency-free tombstone that always fails with migration guidance |## 1. Problem@@ -78,38 +79,34 @@ frozen v5 writer rather than tracking `EXPECTED_SCHEMA_VERSION`. Future schemawork adds explicitly versioned writers and helpers; it must not retarget anexisting helper or derive historical SQL from a mutable package constant.-### 3.3 0.14.0 early-adopter recovery--0.14.1 does not silently detect or mutate `cubeloop_*` databases. The migration-guide contains conspicuous, dialect-specific emergency reverse-rename SQL for a-database that actually ran the withdrawn v6 migration. It instructs operators to:--1. stop all application instances;-2. back up the database;-3. rename tables, all Postgres child partitions, and indexes back;-4. write schema version 5;-5. verify object names and row counts before starting 0.14.1.--The recovery is not part of the normal upgrade path.--The documented SQL is executable source, not an untested snippet. Integration-tests create the exact withdrawn 0.14.0 v6 schema, insert representative data,-execute the documented recovery statements from a shared source verbatim, and-verify v5 names, partitions, indexes, constraints, row counts, version 5, and a-successful 0.14.1 checkpointer round trip. A preflight must detect name-collisions or mixed v5/v6 schemas and fail before executing any rename.--### 3.4 Compatibility distribution--Publish `cubepi==0.14.1` with the real package. Its dependency and forwarded-extras use `cubeloop>=0.14.1,<0.15`, allowing compatible 0.14 patch fixes while-preventing an unreviewed minor-version jump. Both distributions remain versioned-and published together.+### 3.3 No 0.14.0 database recovery surface++Remove the reverse-rename SQL, withdrawn-schema runtime probing, and recovery+guidance. Delete both 0.14.0 distributions during the 0.14.1 release cutover,+after both replacement distributions are downloadable and verified, so package+resolution never falls back to 0.13.6 or to no installable CubeLoop release.+0.14.1 supports the stable v5 `cubepi_*` schema only. A database containing+`cubeloop_*` objects is outside the supported contract; the package neither+detects nor mutates it specially.++### 3.4 Compatibility distribution becomes a tombstone++Publish `cubepi==0.14.1` as a dependency-free tombstone package. It must not+depend on, import, re-export, alias, or dispatch to `cubeloop`. Importing+`cubepi` or any `cubepi.*` path raises `ImportError` immediately with a concise+message naming the replacement package/import and linking to the migration+guide. The package declares no dependencies and no optional-dependency extras.+Running the `cubepi` console script or `python -m cubepi` exits non-zero through+that same import failure, with the same actionable guidance and no CubeLoop+command dispatch. A normal Python import traceback is acceptable for these+command forms; tests assert the non-zero status and guidance text, not polished+CLI rendering.### 3.5 Documentation and frozen 0.14 snapshotUpdate current English and zh-Hans checkpointing/migration docs, backend READMEs,-examples, API reference inputs, and the existing 0.14 versioned snapshot.+examples, API reference inputs, and the existing 0.14 versioned snapshot. State+that 0.14.0 was removed and has no supported database migration.Although frozen snapshots normally do not change, 0.14.0 is withdrawn and 0.14.1is the supported 0.14 release, so the snapshot must describe the safe 0.14contract. Correct only the affected persistence/migration pages in place and@@ -119,19 +116,16 @@ Record this exception in the changelog and release notes.Close PR #223 as superseded, preserving it as incident context.-## 4. Yank and release operations--Yank both `cubeloop==0.14.0` and `cubepi==0.14.0` on PyPI with the reason:--> Withdrawn: the database table rename breaks reproducible host Alembic history-> and safe rollback. Use 0.14.1 or later.+## 4. Delete and release operations-The public incident/recovery page must be live before its link is used. Release-order is: merge and deploy that page; amend the GitHub 0.14.0 release notes;-yank both PyPI projects; then publish 0.14.1. If an emergency yank must happen-before the docs deploy, put self-contained recovery instructions in the GitHub-release notes first. Do not delete artifacts, tags, or the GitHub release.-TestPyPI may be yanked too if supported, but PyPI is the release blocker.+Build both 0.14.1 distributions from the reviewed commit, upload them, and+verify their files and behavior from PyPI. Then, in the same controlled release+window, delete both `cubeloop==0.14.0` and `cubepi==0.14.0` and verify that their+release JSON endpoints no longer advertise downloadable files. Preserve the+GitHub tag/release as incident history and only then amend its notes to say the+package release was removed and users should install 0.14.1. No recovery+procedure is published because the confirmed operational premise is that nobody+adopted 0.14.0.The 0.14.1 release follows the normal patch-release runbook, but does not rerunthe docs-version creation runbook. Do not tag or publish until local Codex review@@ -139,26 +133,25 @@ is clean, CI passes, and the PR Codex review loop is clean.## 5. Acceptance criteria-- Both PyPI 0.14.0 projects report all files as yanked with the agreed reason.+- Both PyPI 0.14.0 projects have no downloadable release files.- A v5 Postgres/MySQL fixture opens and preserves data with 0.14.1 code and no DDL.- Fresh host Alembic history creates only `cubepi_*`, ends at version 5, and thecheckpointer operates on it.- Golden tests prove the complete 0.13.6 helper output and MySQL split contractremain unchanged.-- Both dialects recover an exact v6 fixture with representative data by executing- the shipped recovery source; mixed/colliding schemas fail before mutation.- No supported code or normal docs reference `upgrade_v5_to_v6_op()` or require`cubeloop_*` database objects.- Unit/integration tests, Ruff, formatting, mypy, and docs build pass.-- 0.14.1 wheels smoke-test both `cubeloop` and the `cubepi` shim.+- The 0.14.1 `cubeloop` wheel works normally; the dependency-free `cubepi`+ tombstone wheel fails all imports and commands with migration guidance.- Current and version-0.14 English/zh-Hans docs state that physical DB names stay- `cubepi_*` and include the exceptional 0.14.0 recovery path.+ `cubepi_*` and that 0.14.0 was removed.## 6. Out of scope- Reverting the Python/package/CLI/domain/GitHub rename.- Reverting the new tracing namespace or trace directory.-- Supporting mixed old/new table sets at runtime.+- Supporting, detecting, or recovering mixed old/new table sets at runtime.- Yanking any 0.13.x release.- Renaming the physical database namespace in a later release without a new,separately approved expand/migrate/contract design.diff --git a/tests/checkpointer/test_mysql.py b/tests/checkpointer/test_mysql.pyindex 442fd48..6bf0e0a 100644--- a/tests/checkpointer/test_mysql.py+++ b/tests/checkpointer/test_mysql.py@@ -1,7 +1,5 @@"""MySQLCheckpointer tests — mirrors test_postgres.py."""-from pathlib import Path-import aiomysqlimport pytest@@ -458,7 +456,7 @@ async def test_version_mismatch_raises(clean_mysql_db) -> None:assert exc_info.value.expected == EXPECTED_SCHEMA_VERSIONassert exc_info.value.actual == 999- assert "withdrawn 0.14.0" in str(exc_info.value)+ assert "newer than this CubeLoop release" in str(exc_info.value)assert "call +" not in str(exc_info.value)@@ -680,132 +678,3 @@ async def test_existing_v5_schema_round_trip_without_migration(data = await cp.load("t-mig")assert data is not Noneassert len(data.messages) == 1---async def test_withdrawn_v6_recovery_script_round_trip(clean_mysql_db) -> None:- from cubeloop.checkpointer.mysql import MySQLCheckpointer- from cubeloop.checkpointer.mysql.checkpointer import _parse_dsn- from cubeloop.providers.base import TextContent, UserMessage-- await _setup_schema_v5(clean_mysql_db)- conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))- try:- async with conn.cursor() as cur:- await cur.execute(- "INSERT INTO cubepi_threads (thread_id, extra) VALUES ('kept', JSON_OBJECT())"- )- await cur.execute(- "ALTER TABLE cubepi_messages RENAME INDEX "- "ix_cubepi_messages_thread_run TO ix_cubeloop_messages_thread_run"- )- await cur.execute(- "ALTER TABLE cubepi_runs RENAME INDEX "- "ix_cubepi_runs_thread_seq TO ix_cubeloop_runs_thread_seq"- )- await cur.execute(- "RENAME TABLE cubepi_threads TO cubeloop_threads, "- "cubepi_messages TO cubeloop_messages, "- "cubepi_runs TO cubeloop_runs, "- "cubepi_hitl_answers TO cubeloop_hitl_answers, "- "cubepi_schema_version TO cubeloop_schema_version"- )- await cur.execute("UPDATE cubeloop_schema_version SET version = 6")- script = Path(- "website/static/recovery/0.14.0/mysql-v6-to-v5.sql"- ).read_text()- for statement in script.split(";"):- if statement.strip():- await cur.execute(statement)- await cur.execute(- "SELECT COUNT(*) FROM cubepi_threads WHERE thread_id = 'kept'"- )- assert (await cur.fetchone())[0] == 1- await cur.execute("SELECT version FROM cubepi_schema_version")- assert (await cur.fetchone())[0] == 5- await cur.execute(- "SELECT DISTINCT index_name FROM information_schema.statistics "- "WHERE table_schema = DATABASE()"- )- index_names = {row[0] for row in await cur.fetchall()}- assert "ix_cubepi_messages_thread_run" in index_names- assert "ix_cubepi_runs_thread_seq" in index_names- assert "ix_cubeloop_messages_thread_run" not in index_names- finally:- await conn.ensure_closed()-- async with MySQLCheckpointer(clean_mysql_db) as cp:- await cp.append("recovered", [UserMessage(content=[TextContent(text="ok")])])- data = await cp.load("recovered")- assert data is not None- assert len(data.messages) == 1---async def test_withdrawn_v6_recovery_collision_is_retryable(clean_mysql_db) -> None:- from cubeloop.checkpointer.mysql.checkpointer import _parse_dsn-- await _setup_schema_v5(clean_mysql_db)- conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))- try:- async with conn.cursor() as cur:- await cur.execute(- "RENAME TABLE cubepi_threads TO cubeloop_threads, "- "cubepi_messages TO cubeloop_messages, "- "cubepi_runs TO cubeloop_runs, "- "cubepi_hitl_answers TO cubeloop_hitl_answers, "- "cubepi_schema_version TO cubeloop_schema_version"- )- await cur.execute(- "CREATE TABLE cubepi_threads (thread_id VARCHAR(255) PRIMARY KEY)"- )- script = Path(- "website/static/recovery/0.14.0/mysql-v6-to-v5.sql"- ).read_text()- with pytest.raises(Exception):- for statement in script.split(";"):- if statement.strip():- await cur.execute(statement)- await cur.execute(- "SELECT table_name FROM information_schema.tables "- "WHERE table_schema = DATABASE() AND table_name IN "- "('cubeloop_threads', 'cubepi_threads')"- )- assert {row[0] for row in await cur.fetchall()} == {- "cubeloop_threads",- "cubepi_threads",- }- await cur.execute("DROP TABLE cubepi_threads")- for statement in script.split(";"):- if statement.strip():- await cur.execute(statement)- await cur.execute(- "SELECT COUNT(*) FROM information_schema.routines "- "WHERE routine_schema = DATABASE() "- "AND routine_name = 'cubeloop_0140_recovery_preflight'"- )- assert (await cur.fetchone())[0] == 0- finally:- await conn.ensure_closed()---async def test_withdrawn_v6_schema_points_to_recovery(clean_mysql_db) -> None:- from cubeloop.checkpointer.mysql import CubeloopSchemaMismatch, MySQLCheckpointer- from cubeloop.checkpointer.mysql.checkpointer import _parse_dsn-- conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))- try:- async with conn.cursor() as cur:- await cur.execute(- "CREATE TABLE cubeloop_schema_version "- "(version INT PRIMARY KEY) ENGINE=InnoDB"- )- await cur.execute("INSERT INTO cubeloop_schema_version VALUES (6)")- finally:- await conn.ensure_closed()- with pytest.raises(CubeloopSchemaMismatch) as exc_info:- async with MySQLCheckpointer(clean_mysql_db):- pass- assert exc_info.value.actual == 6- assert "withdrawn 0.14.0" in str(exc_info.value)diff --git a/tests/checkpointer/test_postgres.py b/tests/checkpointer/test_postgres.pyindex 23f3bb4..52b16ec 100644--- a/tests/checkpointer/test_postgres.py+++ b/tests/checkpointer/test_postgres.py@@ -3,8 +3,6 @@Full E2E tests are in D1.3 once PostgresCheckpointer is implemented."""-from pathlib import Path-import asyncpgimport pytest@@ -508,102 +506,6 @@ async def test_existing_v5_schema_round_trip_without_migration(clean_db) -> Noneassert len(data.messages) == 1-async def test_withdrawn_v6_recovery_script_round_trip(clean_db) -> None:- from cubeloop.checkpointer.postgres import PostgresCheckpointer- from cubeloop.providers.base import TextContent, UserMessage-- await _setup_schema_v5(clean_db)- conn = await asyncpg.connect(clean_db)- try:- await conn.execute(- "INSERT INTO cubepi_threads (thread_id, extra) VALUES ('kept', '{}')"- )- await conn.execute("ALTER TABLE cubepi_threads RENAME TO cubeloop_threads")- await conn.execute("ALTER TABLE cubepi_messages RENAME TO cubeloop_messages")- for i in range(64):- await conn.execute(- f"ALTER TABLE cubepi_messages_p{i:02d} "- f"RENAME TO cubeloop_messages_p{i:02d}"- )- await conn.execute("ALTER TABLE cubepi_runs RENAME TO cubeloop_runs")- for i in range(64):- await conn.execute(- f"ALTER TABLE cubepi_runs_p{i:02d} RENAME TO cubeloop_runs_p{i:02d}"- )- await conn.execute(- "ALTER TABLE cubepi_hitl_answers RENAME TO cubeloop_hitl_answers"- )- await conn.execute(- "ALTER TABLE cubepi_schema_version RENAME TO cubeloop_schema_version"- )- await conn.execute(- "ALTER INDEX ix_cubepi_messages_metadata_gin "- "RENAME TO ix_cubeloop_messages_metadata_gin"- )- await conn.execute(- "ALTER INDEX ix_cubepi_messages_thread_run "- "RENAME TO ix_cubeloop_messages_thread_run"- )- await conn.execute(- "ALTER INDEX ix_cubepi_runs_thread_seq "- "RENAME TO ix_cubeloop_runs_thread_seq"- )- await conn.execute("UPDATE cubeloop_schema_version SET version = 6")- await conn.execute(- Path("website/static/recovery/0.14.0/postgres-v6-to-v5.sql").read_text()- )- assert (- await conn.fetchval(- "SELECT count(*) FROM cubepi_threads WHERE thread_id = 'kept'"- )- == 1- )- assert await conn.fetchval("SELECT version FROM cubepi_schema_version") == 5- assert (- await conn.fetchval(- "SELECT count(*) FROM pg_inherits i "- "JOIN pg_class p ON p.oid = i.inhparent "- "WHERE p.relname IN ('cubepi_messages', 'cubepi_runs')"- )- == 128- )- index_names = {- row["indexname"]- for row in await conn.fetch(- "SELECT indexname FROM pg_indexes WHERE schemaname = current_schema()"- )- }- assert "ix_cubepi_messages_thread_run" in index_names- assert "ix_cubepi_runs_thread_seq" in index_names- finally:- await conn.close()-- async with PostgresCheckpointer(clean_db) as cp:- await cp.append("recovered", [UserMessage(content=[TextContent(text="ok")])])- data = await cp.load("recovered")- assert data is not None- assert len(data.messages) == 1---async def test_withdrawn_v6_recovery_collision_is_atomic(clean_db) -> None:- await _setup_schema_v5(clean_db)- conn = await asyncpg.connect(clean_db)- try:- await conn.execute("ALTER TABLE cubepi_threads RENAME TO cubeloop_threads")- await conn.execute("CREATE TABLE cubepi_threads (thread_id TEXT PRIMARY KEY)")- with pytest.raises(asyncpg.PostgresError):- await conn.execute(- Path("website/static/recovery/0.14.0/postgres-v6-to-v5.sql").read_text()- )- await conn.execute("ROLLBACK")- assert await conn.fetchval("SELECT to_regclass('cubeloop_threads')")- assert await conn.fetchval("SELECT to_regclass('cubepi_threads')")- finally:- await conn.close()--@pytest.mark.asyncioasync def test_data_tables_without_version_table_are_not_uninitialized(clean_db,@@ -629,30 +531,3 @@ async def test_data_tables_without_version_table_are_not_uninitialized(passassert "Uninitialized" not in type(ei.value).__name__assert not isinstance(ei.value, CubeloopSchemaUninitialized)--[email protected]("stored_version", [5, 6])-async def test_withdrawn_v6_schema_points_to_recovery(- clean_db, stored_version: int-) -> None:- from cubeloop.checkpointer.postgres import (- CubeloopSchemaMismatch,- PostgresCheckpointer,- )-- conn = await asyncpg.connect(clean_db)- try:- await conn.execute(- "CREATE TABLE cubeloop_schema_version (version INTEGER PRIMARY KEY)"- )- await conn.execute(- "INSERT INTO cubeloop_schema_version VALUES ($1)", stored_version- )- finally:- await conn.close()- with pytest.raises(CubeloopSchemaMismatch) as exc_info:- async with PostgresCheckpointer(clean_db):- pass- assert exc_info.value.actual == stored_version- assert "withdrawn 0.14.0" in str(exc_info.value)diff --git a/tests/checkpointer/test_postgres_schema.py b/tests/checkpointer/test_postgres_schema.pyindex 69d54f4..07c8470 100644--- a/tests/checkpointer/test_postgres_schema.py+++ b/tests/checkpointer/test_postgres_schema.py@@ -15,9 +15,9 @@ def test_schema_mismatch_hint_names_every_step_across_multiple_versions():assert "upgrade_v4_to_v5_op()" in hint-def test_newer_schema_hint_points_to_withdrawn_release_recovery():+def test_newer_schema_hint_is_actionable():hint = _schema_mismatch_hint(actual=6, expected=5)- assert "withdrawn 0.14.0" in hint+ assert "newer than this CubeLoop release" in hintassert "call +" not in hintdiff --git a/tests/compat/test_cubepi_shim.py b/tests/compat/test_cubepi_shim.pyindex be1ab3d..e3bdad9 100644--- a/tests/compat/test_cubepi_shim.py+++ b/tests/compat/test_cubepi_shim.py@@ -1,85 +1,56 @@-"""Transitional cubepi shim — import alias, warning, lazy tracing."""+"""The removed ``cubepi`` name fails with actionable migration guidance."""from __future__ import annotationsimport subprocess+import shutilimport sys-import warningsimport pytest-def test_import_cubepi_warns_and_reexports() -> None:- import cubeloop-- with warnings.catch_warnings(record=True) as caught:- warnings.simplefilter("always")- import cubepi- assert cubepi.Agent is cubeloop.Agent- assert any(issubclass(w.category, DeprecationWarning) for w in caught)---def test_deep_import_aliases_provider() -> None:- from cubepi.providers.anthropic import AnthropicProvider- from cubeloop.providers.anthropic import AnthropicProvider as Direct-- assert AnthropicProvider is Direct---def test_deep_import_checkpointer() -> None:- from cubepi.checkpointer.postgres import PostgresCheckpointer- from cubeloop.checkpointer.postgres import PostgresCheckpointer as Direct-- assert PostgresCheckpointer is Direct---def test_tracing_schema_lazy_without_otel() -> None:- code = (- "import builtins, sys\n"- "real_import = builtins.__import__\n"- "def fake(name, *a, **k):\n"- " if name == 'opentelemetry' or name.startswith('opentelemetry.'):\n"- " raise ImportError('hidden')\n"- " return real_import(name, *a, **k)\n"- "builtins.__import__ = fake\n"- "from cubepi.tracing import schema\n"- "assert schema.CUBELOOP_RUN_ID == 'cubeloop.run_id'\n"- "print('ok')\n"- )+ "statement",+ [+ "import cubepi",+ "import cubepi.agent",+ "from cubepi.providers.anthropic import AnthropicProvider",+ "from cubepi.checkpointer.postgres import PostgresCheckpointer",+ "from cubepi.tracing import schema",+ ],+)+def test_imports_fail_with_migration_guidance(statement: str) -> None:result = subprocess.run(- [sys.executable, "-c", code], capture_output=True, text=True+ [sys.executable, "-c", statement], capture_output=True, text=True)- assert result.returncode == 0, result.stderr- assert "ok" in result.stdout+ assert result.returncode != 0+ assert "ImportError" in result.stderr+ assert "Install 'cubeloop'" in result.stderr+ assert "replace 'cubepi' imports with 'cubeloop'" in result.stderr+ assert "https://cubeloop.dev/docs/migration/from-cubepi" in result.stderr-def test_python_m_cubepi_trace_help() -> None:- result = subprocess.run(+ "arguments",+ [+ [sys.executable, "-m", "cubepi"],[sys.executable, "-m", "cubepi", "trace", "--help"],- capture_output=True,- text=True,- )- assert result.returncode == 0, result.stderr- assert "renamed to 'cubeloop'" in result.stderr- assert "trace" in result.stdout---def test_python_m_cubepi_cli_help() -> None:- result = subprocess.run([sys.executable, "-m", "cubepi.cli", "--help"],- capture_output=True,- text=True,- )- assert result.returncode == 0, result.stderr- assert "trace" in result.stdout---def test_second_import_does_not_reprint(capsys: pytest.CaptureFixture[str]) -> None:- import cubepi # noqa: F401-- capsys.readouterr()- import importlib-- importlib.reload(cubepi)- captured = capsys.readouterr()- assert "renamed to 'cubeloop'" not in captured.err+ ],+)+def test_module_commands_fail_with_migration_guidance(+ arguments: list[str],+) -> None:+ result = subprocess.run(arguments, capture_output=True, text=True)+ assert result.returncode != 0+ assert "Install 'cubeloop'" in result.stderr+ assert "https://cubeloop.dev/docs/migration/from-cubepi" in result.stderr+++def test_console_command_fails_with_migration_guidance() -> None:+ command = shutil.which("cubepi")+ assert command is not None+ result = subprocess.run([command], capture_output=True, text=True)+ assert result.returncode != 0+ assert "Install 'cubeloop'" in result.stderr+ assert "https://cubeloop.dev/docs/migration/from-cubepi" in result.stderrdiff --git a/tests/providers/test_faux.py b/tests/providers/test_faux.pyindex e4c1dcf..b10f7dd 100644--- a/tests/providers/test_faux.py+++ b/tests/providers/test_faux.py@@ -650,14 +650,14 @@ class TestCanAcceptExtendedArgs:def test_returns_false_when_signature_raises_value_error(self):"""When inspect.signature raises ValueError, should return False."""with patch(- "cubepi.providers.faux.inspect.signature", side_effect=ValueError("boom")+ "cubeloop.providers.faux.inspect.signature", side_effect=ValueError("boom")):assert _can_accept_extended_args(lambda: None) is Falsedef test_returns_false_when_signature_raises_type_error(self):"""When inspect.signature raises TypeError, should return False."""with patch(- "cubepi.providers.faux.inspect.signature", side_effect=TypeError("boom")+ "cubeloop.providers.faux.inspect.signature", side_effect=TypeError("boom")):assert _can_accept_extended_args(lambda: None) is Falsediff --git a/uv.lock b/uv.lockindex 618f90e..463680d 100644--- a/uv.lock+++ b/uv.lock@@ -626,45 +626,6 @@ dev = [name = "cubepi"version = "0.14.1"source = { editable = "compat/cubepi" }-dependencies = [- { name = "cubeloop" },-]--[package.optional-dependencies]-mcp = [- { name = "cubeloop", extra = ["mcp"] },-]-mysql = [- { name = "cubeloop", extra = ["mysql"] },-]-postgres = [- { name = "cubeloop", extra = ["postgres"] },-]-sqlite = [- { name = "cubeloop", extra = ["sqlite"] },-]-trace-cli = [- { name = "cubeloop", extra = ["trace-cli"] },-]-tracing = [- { name = "cubeloop", extra = ["tracing"] },-]-tracing-otlp = [- { name = "cubeloop", extra = ["tracing-otlp"] },-]--[package.metadata]-requires-dist = [- { name = "cubeloop", editable = "." },- { name = "cubeloop", extras = ["mcp"], marker = "extra == 'mcp'", editable = "." },- { name = "cubeloop", extras = ["mysql"], marker = "extra == 'mysql'", editable = "." },- { name = "cubeloop", extras = ["postgres"], marker = "extra == 'postgres'", editable = "." },- { name = "cubeloop", extras = ["sqlite"], marker = "extra == 'sqlite'", editable = "." },- { name = "cubeloop", extras = ["trace-cli"], marker = "extra == 'trace-cli'", editable = "." },- { name = "cubeloop", extras = ["tracing"], marker = "extra == 'tracing'", editable = "." },- { name = "cubeloop", extras = ["tracing-otlp"], marker = "extra == 'tracing-otlp'", editable = "." },-]-provides-extras = ["sqlite", "postgres", "mysql", "mcp", "tracing", "tracing-otlp", "trace-cli"][[package]]name = "distro"diff --git a/website/docs/guides/checkpointing/mysql.md b/website/docs/guides/checkpointing/mysql.mdindex 29e3b49..40d602e 100644--- a/website/docs/guides/checkpointing/mysql.md+++ b/website/docs/guides/checkpointing/mysql.md@@ -262,8 +262,7 @@ def upgrade():The package rename does not change the persistence schema: physical names stay`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need-no migration. See the [migration guide](../../migration/from-cubepi), including-the exceptional recovery path for withdrawn 0.14.0.+no migration. See the [migration guide](../../migration/from-cubepi).## Common pitfallsdiff --git a/website/docs/guides/checkpointing/postgres.md b/website/docs/guides/checkpointing/postgres.mdindex 938a20b..1500135 100644--- a/website/docs/guides/checkpointing/postgres.md+++ b/website/docs/guides/checkpointing/postgres.md@@ -250,8 +250,7 @@ def upgrade():The package rename does not change the persistence schema: physical names stay`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need-no migration. See the [migration guide](../../migration/from-cubepi), including-the exceptional recovery path for withdrawn 0.14.0.+no migration. See the [migration guide](../../migration/from-cubepi).## Common pitfallsdiff --git a/website/docs/migration/from-cubepi.md b/website/docs/migration/from-cubepi.mdindex e201c52..c075245 100644--- a/website/docs/migration/from-cubepi.md+++ b/website/docs/migration/from-cubepi.md@@ -21,12 +21,11 @@ from cubeloop import Agent, toolfrom cubeloop.providers.anthropic import AnthropicProvider```-`pip install -U cubepi` still works: 0.14.1+ is a wrapper that depends on a-compatible CubeLoop 0.14 release, re-exports the public API, and aliases-`cubepi.*` imports.-It warns on first import. Prefer depending on `cubeloop` directly.+`cubepi` 0.14.1+ is a tombstone package: it has no CubeLoop dependency and all+`cubepi` imports fail with migration instructions. Replace the dependency and+all imports explicitly; there is no compatibility proxy.-CLI: `cubeloop trace` (the wrapper still provides `cubepi trace` and warns).+CLI: replace `cubepi trace` with `cubeloop trace`.## Checkpointer schema stays at v5@@ -39,19 +38,8 @@ Historical host Alembic revisions may import helpers from`cubeloop.checkpointer.*.alembic_helpers`; those helpers retain their originalv1–v5 SQL. Do not add a rename revision.-### Emergency recovery from withdrawn 0.14.0--0.14.0 was yanked because it briefly renamed these database objects to-`cubeloop_*`. Only use this recovery if 0.14.0 created the database or you ran its withdrawn-migration. Stop every application instance, take a verified backup, then run-the script for your database with an administrative SQL client:--- [Postgres v6→v5 recovery SQL](/recovery/0.14.0/postgres-v6-to-v5.sql)-- [MySQL v6→v5 recovery SQL](/recovery/0.14.0/mysql-v6-to-v5.sql)--The scripts refuse mixed/colliding schemas before renaming anything. Afterward,-verify table and row counts, then deploy 0.14.1. Do not run them on a normal v5-database.+Upgrade directly from 0.13.6 or earlier to 0.14.1 or later. No database+migration is required.## Tracingdiff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.mdindex 33323fd..a975ede 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.md@@ -188,7 +188,7 @@ def upgrade():## CubeLoop 更名-包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。详见[迁移指南](../../migration/from-cubepi)。## 常见陷阱diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.mdindex 5b1e129..34c8a1d 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md@@ -203,7 +203,7 @@ def upgrade():## CubeLoop 更名-包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。详见[迁移指南](../../migration/from-cubepi)。## 常见坑diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.mdindex e2da14e..11a73e7 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.md@@ -20,11 +20,10 @@ from cubeloop import Agent, toolfrom cubeloop.providers.anthropic import AnthropicProvider```-`pip install -U cubepi` 仍可使用:0.14.1+ 是兼容包装,依赖同一 0.14 系列的-CubeLoop,重新导出公共 API,并为 `cubepi.*` 深层导入提供别名。首次导入会告警,-新项目应直接依赖 `cubeloop`。+`cubepi` 0.14.1+ 是不带依赖的占位包。所有 `cubepi` 导入都会直接报错并提示迁移,+不会安装或代理 CubeLoop。请明确替换项目依赖和全部 import。-CLI 改为 `cubeloop trace`;包装包仍提供会告警的 `cubepi trace`。+CLI 请将 `cubepi trace` 替换为 `cubeloop trace`。## Checkpointer schema 保持 v5@@ -35,17 +34,7 @@ Postgres 和 MySQL 的物理表名、分区名和索引名继续使用 `cubepi_*历史 Alembic revision 可以继续从 `cubeloop.checkpointer.*.alembic_helpers`导入 helper;这些 helper 保持原来的 v1–v5 SQL。不要添加表名 rename revision。-### 从已撤回的 0.14.0 紧急恢复--0.14.0 曾短暂把数据库对象改成 `cubeloop_*`,因此已被 yank。只有确实执行过-那条迁移时才使用下面的恢复脚本。先停止全部应用实例并完成可验证备份,再用-数据库管理客户端执行对应脚本:--- [Postgres v6→v5 恢复脚本](/recovery/0.14.0/postgres-v6-to-v5.sql)-- [MySQL v6→v5 恢复脚本](/recovery/0.14.0/mysql-v6-to-v5.sql)--脚本会在修改前拒绝混合或冲突 schema。完成后核对表和行数,再部署 0.14.1。-正常 v5 数据库不要执行这些脚本。+从 0.13.6 或更早版本直接升级到 0.14.1 或更高版本,不需要数据库迁移。## Tracingdiff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.mdindex 33323fd..a975ede 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.md@@ -188,7 +188,7 @@ def upgrade():## CubeLoop 更名-包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。详见[迁移指南](../../migration/from-cubepi)。## 常见陷阱diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.mdindex 5b1e129..34c8a1d 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.md@@ -203,7 +203,7 @@ def upgrade():## CubeLoop 更名-包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。详见[迁移指南](../../migration/from-cubepi)。## 常见坑diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/intro.mdx b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/intro.mdxindex 1ecd67a..90ff31f 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/intro.mdx+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/intro.mdx@@ -68,9 +68,10 @@ pip install cubeloop用于安装 CubeLoop 和构建 0.14 发布 API。CubeLoop 0.14 将 CubePi / `cubepi` 重命名为 CubeLoop / `cubeloop`:导入路径、-PyPI 项目、CLI、文档站(`https://cubeloop.dev`)、OTel vendor 命名空间-(`cubeloop.*`)、以及 Postgres/MySQL 表名(`cubeloop_*`)。-`pip install cubepi` 0.14+ 是依赖 `cubeloop` 并告警的过渡包装。详见+PyPI 项目、CLI、文档站(`https://cubeloop.dev`)和 OTel vendor 命名空间+(`cubeloop.*`)。+Postgres/MySQL 的物理名称继续使用 `cubepi_*`,schema version 保持 5。+`cubepi` 0.14.1+ 是不带依赖的占位包,导入和命令会直接报错并提示迁移。详见[迁移指南](./migration/from-cubepi.md)。源代码、Issue 和讨论都在diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.mdindex e2da14e..11a73e7 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.md@@ -20,11 +20,10 @@ from cubeloop import Agent, toolfrom cubeloop.providers.anthropic import AnthropicProvider```-`pip install -U cubepi` 仍可使用:0.14.1+ 是兼容包装,依赖同一 0.14 系列的-CubeLoop,重新导出公共 API,并为 `cubepi.*` 深层导入提供别名。首次导入会告警,-新项目应直接依赖 `cubeloop`。+`cubepi` 0.14.1+ 是不带依赖的占位包。所有 `cubepi` 导入都会直接报错并提示迁移,+不会安装或代理 CubeLoop。请明确替换项目依赖和全部 import。-CLI 改为 `cubeloop trace`;包装包仍提供会告警的 `cubepi trace`。+CLI 请将 `cubepi trace` 替换为 `cubeloop trace`。## Checkpointer schema 保持 v5@@ -35,17 +34,7 @@ Postgres 和 MySQL 的物理表名、分区名和索引名继续使用 `cubepi_*历史 Alembic revision 可以继续从 `cubeloop.checkpointer.*.alembic_helpers`导入 helper;这些 helper 保持原来的 v1–v5 SQL。不要添加表名 rename revision。-### 从已撤回的 0.14.0 紧急恢复--0.14.0 曾短暂把数据库对象改成 `cubeloop_*`,因此已被 yank。只有确实执行过-那条迁移时才使用下面的恢复脚本。先停止全部应用实例并完成可验证备份,再用-数据库管理客户端执行对应脚本:--- [Postgres v6→v5 恢复脚本](/recovery/0.14.0/postgres-v6-to-v5.sql)-- [MySQL v6→v5 恢复脚本](/recovery/0.14.0/mysql-v6-to-v5.sql)--脚本会在修改前拒绝混合或冲突 schema。完成后核对表和行数,再部署 0.14.1。-正常 v5 数据库不要执行这些脚本。+从 0.13.6 或更早版本直接升级到 0.14.1 或更高版本,不需要数据库迁移。## Tracingdiff --git a/website/static/recovery/0.14.0/mysql-v6-to-v5.sql b/website/static/recovery/0.14.0/mysql-v6-to-v5.sqldeleted file mode 100644index 52df85e..0000000--- a/website/static/recovery/0.14.0/mysql-v6-to-v5.sql+++ /dev/null@@ -1,68 +0,0 @@--- Emergency recovery for databases created or migrated by withdrawn 0.14.0.--- Stop all application instances and take a backup before running this file.-SET @cp_new_tables = (- SELECT COUNT(*) FROM information_schema.tables- WHERE table_schema = DATABASE() AND table_name IN (- 'cubeloop_threads', 'cubeloop_messages', 'cubeloop_runs',- 'cubeloop_hitl_answers', 'cubeloop_schema_version'- )-);-SET @cp_old_tables = (- SELECT COUNT(*) FROM information_schema.tables- WHERE table_schema = DATABASE() AND table_name IN (- 'cubepi_threads', 'cubepi_messages', 'cubepi_runs',- 'cubepi_hitl_answers', 'cubepi_schema_version'- )-);-SET @cp_new_indexes = (- SELECT COUNT(DISTINCT index_name) FROM information_schema.statistics- WHERE table_schema = DATABASE() AND index_name IN (- 'ix_cubeloop_messages_metadata_gin',- 'ix_cubeloop_messages_thread_run', 'ix_cubeloop_runs_thread_seq'- )-);-SET @cp_old_indexes = (- SELECT COUNT(DISTINCT index_name) FROM information_schema.statistics- WHERE table_schema = DATABASE() AND index_name IN (- 'ix_cubepi_messages_metadata_gin',- 'ix_cubepi_messages_thread_run', 'ix_cubepi_runs_thread_seq'- )-);-SET @cp_fresh_indexes = (@cp_new_indexes > 0);-SET @cp_guard = IF(- @cp_new_tables = 5 AND @cp_old_tables = 0- AND ((@cp_new_indexes = 0 AND @cp_old_indexes = 2)- OR (@cp_new_indexes = 2 AND @cp_old_indexes = 0)),- 'DO 0',- 'SELECT * FROM cubeloop_0140_recovery_preflight_failed'-);-PREPARE cp_guard FROM @cp_guard;-EXECUTE cp_guard;-DEALLOCATE PREPARE cp_guard;--RENAME TABLE- cubeloop_threads TO cubepi_threads,- cubeloop_messages TO cubepi_messages,- cubeloop_runs TO cubepi_runs,- cubeloop_hitl_answers TO cubepi_hitl_answers,- cubeloop_schema_version TO cubepi_schema_version;--SET @cp_rename_message_index = IF(- @cp_fresh_indexes,- 'ALTER TABLE cubepi_messages RENAME INDEX ix_cubeloop_messages_thread_run TO ix_cubepi_messages_thread_run',- 'DO 0'-);-PREPARE cp_stmt FROM @cp_rename_message_index;-EXECUTE cp_stmt;-DEALLOCATE PREPARE cp_stmt;-SET @cp_rename_run_index = IF(- @cp_fresh_indexes,- 'ALTER TABLE cubepi_runs RENAME INDEX ix_cubeloop_runs_thread_seq TO ix_cubepi_runs_thread_seq',- 'DO 0'-);-PREPARE cp_stmt FROM @cp_rename_run_index;-EXECUTE cp_stmt;-DEALLOCATE PREPARE cp_stmt;--DELETE FROM cubepi_schema_version WHERE version <> 5;-INSERT IGNORE INTO cubepi_schema_version (version) VALUES (5);diff --git a/website/static/recovery/0.14.0/postgres-v6-to-v5.sql b/website/static/recovery/0.14.0/postgres-v6-to-v5.sqldeleted file mode 100644index 91c60fb..0000000--- a/website/static/recovery/0.14.0/postgres-v6-to-v5.sql+++ /dev/null@@ -1,83 +0,0 @@--- Emergency recovery for databases migrated by withdrawn cubeloop 0.14.0.--- Stop all application instances and take a backup before running this file.-BEGIN;--DO $$-DECLARE- schema_name text := current_schema();- new_count integer;- old_count integer;- new_index_count integer;- old_index_count integer;- i integer;-BEGIN- SELECT count(*) INTO new_count- FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace- WHERE relname IN (- 'cubeloop_threads', 'cubeloop_messages', 'cubeloop_runs',- 'cubeloop_hitl_answers', 'cubeloop_schema_version'- ) AND n.nspname = schema_name;- SELECT count(*) INTO old_count- FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace- WHERE relname IN (- 'cubepi_threads', 'cubepi_messages', 'cubepi_runs',- 'cubepi_hitl_answers', 'cubepi_schema_version'- ) AND n.nspname = schema_name;- IF new_count <> 5 OR old_count <> 0 THEN- RAISE EXCEPTION- 'expected a complete 0.14.0 schema (5 cubeloop tables, 0 cubepi tables); found % and %',- new_count, old_count;- END IF;- SELECT count(*) INTO new_index_count- FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace- WHERE relkind IN ('i', 'I') AND relname IN (- 'ix_cubeloop_messages_metadata_gin',- 'ix_cubeloop_messages_thread_run', 'ix_cubeloop_runs_thread_seq'- ) AND n.nspname = schema_name;- SELECT count(*) INTO old_index_count- FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace- WHERE relkind IN ('i', 'I') AND relname IN (- 'ix_cubepi_messages_metadata_gin',- 'ix_cubepi_messages_thread_run', 'ix_cubepi_runs_thread_seq'- ) AND n.nspname = schema_name;- IF new_index_count <> 3 OR old_index_count <> 0 THEN- RAISE EXCEPTION- 'index preflight failed: expected 3 cubeloop indexes and 0 cubepi indexes';- END IF;-- FOR i IN 0..63 LOOP- IF to_regclass(format('%I.%I', schema_name, 'cubeloop_messages_p' || lpad(i::text, 2, '0'))) IS NULL- OR to_regclass(format('%I.%I', schema_name, 'cubeloop_runs_p' || lpad(i::text, 2, '0'))) IS NULL- OR to_regclass(format('%I.%I', schema_name, 'cubepi_messages_p' || lpad(i::text, 2, '0'))) IS NOT NULL- OR to_regclass(format('%I.%I', schema_name, 'cubepi_runs_p' || lpad(i::text, 2, '0'))) IS NOT NULL THEN- RAISE EXCEPTION 'partition preflight failed at suffix %', i;- END IF;- END LOOP;-- EXECUTE format('ALTER TABLE %I.cubeloop_threads RENAME TO cubepi_threads', schema_name);- EXECUTE format('ALTER TABLE %I.cubeloop_messages RENAME TO cubepi_messages', schema_name);- FOR i IN 0..63 LOOP- EXECUTE format(- 'ALTER TABLE %I.%I RENAME TO %I', schema_name,- 'cubeloop_messages_p' || lpad(i::text, 2, '0'),- 'cubepi_messages_p' || lpad(i::text, 2, '0')- );- END LOOP;- EXECUTE format('ALTER TABLE %I.cubeloop_runs RENAME TO cubepi_runs', schema_name);- FOR i IN 0..63 LOOP- EXECUTE format(- 'ALTER TABLE %I.%I RENAME TO %I', schema_name,- 'cubeloop_runs_p' || lpad(i::text, 2, '0'),- 'cubepi_runs_p' || lpad(i::text, 2, '0')- );- END LOOP;- EXECUTE format('ALTER TABLE %I.cubeloop_hitl_answers RENAME TO cubepi_hitl_answers', schema_name);- EXECUTE format('ALTER TABLE %I.cubeloop_schema_version RENAME TO cubepi_schema_version', schema_name);- EXECUTE format('ALTER INDEX %I.ix_cubeloop_messages_metadata_gin RENAME TO ix_cubepi_messages_metadata_gin', schema_name);- EXECUTE format('ALTER INDEX %I.ix_cubeloop_messages_thread_run RENAME TO ix_cubepi_messages_thread_run', schema_name);- EXECUTE format('ALTER INDEX %I.ix_cubeloop_runs_thread_seq RENAME TO ix_cubepi_runs_thread_seq', schema_name);- EXECUTE format('DELETE FROM %I.cubepi_schema_version WHERE version <> 5', schema_name);- EXECUTE format('INSERT INTO %I.cubepi_schema_version (version) VALUES (5) ON CONFLICT DO NOTHING', schema_name);-END $$;--COMMIT;diff --git a/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md b/website/versioned_docs/version-0.14/guides/checkpointing/mysql.mdindex 29e3b49..40d602e 100644--- a/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md+++ b/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md@@ -262,8 +262,7 @@ def upgrade():The package rename does not change the persistence schema: physical names stay`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need-no migration. See the [migration guide](../../migration/from-cubepi), including-the exceptional recovery path for withdrawn 0.14.0.+no migration. See the [migration guide](../../migration/from-cubepi).## Common pitfallsdiff --git a/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md b/website/versioned_docs/version-0.14/guides/checkpointing/postgres.mdindex 938a20b..1500135 100644--- a/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md+++ b/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md@@ -250,8 +250,7 @@ def upgrade():The package rename does not change the persistence schema: physical names stay`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need-no migration. See the [migration guide](../../migration/from-cubepi), including-the exceptional recovery path for withdrawn 0.14.0.+no migration. See the [migration guide](../../migration/from-cubepi).## Common pitfallsdiff --git a/website/versioned_docs/version-0.14/intro.mdx b/website/versioned_docs/version-0.14/intro.mdxindex 5311ac0..ed9182d 100644--- a/website/versioned_docs/version-0.14/intro.mdx+++ b/website/versioned_docs/version-0.14/intro.mdx@@ -74,10 +74,11 @@ documentation set for installing CubeLoop and building against the published0.14 API.CubeLoop 0.14 renames CubePi / `cubepi` to CubeLoop / `cubeloop`: import-path, PyPI project, CLI, docs site (`https://cubeloop.dev`), OTel vendor-namespace (`cubeloop.*`), and Postgres/MySQL table names (`cubeloop_*`).-`pip install cubepi` 0.14+ is a transitional wrapper that depends on-`cubeloop` and warns. See the [migration guide](./migration/from-cubepi.md).+path, PyPI project, CLI, docs site (`https://cubeloop.dev`), and OTel vendor+namespace (`cubeloop.*`). Persistent Postgres/MySQL names remain `cubepi_*` at+schema v5. The `cubepi` 0.14.1+ distribution is a dependency-free tombstone;+imports and commands fail with migration guidance. See the+[migration guide](./migration/from-cubepi.md).Source, issues, and discussion live on[GitHub](https://github.com/cubeplexai/cubeloop).diff --git a/website/versioned_docs/version-0.14/migration/from-cubepi.md b/website/versioned_docs/version-0.14/migration/from-cubepi.mdindex e201c52..c075245 100644--- a/website/versioned_docs/version-0.14/migration/from-cubepi.md+++ b/website/versioned_docs/version-0.14/migration/from-cubepi.md@@ -21,12 +21,11 @@ from cubeloop import Agent, toolfrom cubeloop.providers.anthropic import AnthropicProvider```-`pip install -U cubepi` still works: 0.14.1+ is a wrapper that depends on a-compatible CubeLoop 0.14 release, re-exports the public API, and aliases-`cubepi.*` imports.-It warns on first import. Prefer depending on `cubeloop` directly.+`cubepi` 0.14.1+ is a tombstone package: it has no CubeLoop dependency and all+`cubepi` imports fail with migration instructions. Replace the dependency and+all imports explicitly; there is no compatibility proxy.-CLI: `cubeloop trace` (the wrapper still provides `cubepi trace` and warns).+CLI: replace `cubepi trace` with `cubeloop trace`.## Checkpointer schema stays at v5@@ -39,19 +38,8 @@ Historical host Alembic revisions may import helpers from`cubeloop.checkpointer.*.alembic_helpers`; those helpers retain their originalv1–v5 SQL. Do not add a rename revision.-### Emergency recovery from withdrawn 0.14.0--0.14.0 was yanked because it briefly renamed these database objects to-`cubeloop_*`. Only use this recovery if 0.14.0 created the database or you ran its withdrawn-migration. Stop every application instance, take a verified backup, then run-the script for your database with an administrative SQL client:--- [Postgres v6→v5 recovery SQL](/recovery/0.14.0/postgres-v6-to-v5.sql)-- [MySQL v6→v5 recovery SQL](/recovery/0.14.0/mysql-v6-to-v5.sql)--The scripts refuse mixed/colliding schemas before renaming anything. Afterward,-verify table and row counts, then deploy 0.14.1. Do not run them on a normal v5-database.+Upgrade directly from 0.13.6 or earlier to 0.14.1 or later. No database+migration is required.## Tracing