pantheon-opencode 1.6.0-beta.14 → 1.6.0-beta.17
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.global.md +8 -10
- package/AGENTS.md +1 -1
- package/CHANGELOG.md +62 -3
- package/README.md +155 -24
- package/README.pt-BR.md +14 -14
- package/package.json +3 -3
- package/plugin.json +1 -1
- package/pyproject.toml +1 -1
- package/scripts/_pantheon_paths.py +24 -0
- package/scripts/doctor.mjs +7 -2
- package/scripts/install-mcp.mjs +1 -1
- package/scripts/mcp_persistence.py +1260 -1017
- package/scripts/memory_mcp.py +12 -843
- package/scripts/test-opencode-v2-sandbox.sh +2 -115
- package/skills-lock.json +3 -3
- package/src/agents/aphrodite.md +11 -10
- package/src/agents/apollo.md +1 -2
- package/src/agents/athena.md +13 -13
- package/src/agents/demeter.md +10 -7
- package/src/agents/gaia.md +0 -1
- package/src/agents/hephaestus.md +4 -3
- package/src/agents/hermes.md +10 -9
- package/src/agents/iris.md +0 -1
- package/src/agents/mnemosyne.md +3 -2
- package/src/agents/nyx.md +4 -4
- package/src/agents/prometheus.md +12 -11
- package/src/agents/zeus.md +27 -2
- package/src/instructions/agent-return-format.instructions.md +7 -9
- package/src/instructions/zeus-council-synthesis.instructions.md +2 -2
- package/src/instructions/zeus-memory-operations.instructions.md +9 -1
- package/src/instructions/zeus-timeout-retry.instructions.md +8 -1
- package/src/mcp/_pantheon_paths.py +24 -0
- package/src/mcp/mcp_codemap_module.py +86 -18
- package/src/mcp/mcp_persistence.py +1260 -1017
- package/src/mcp/memory_mcp.py +101 -57
- package/src/pantheon/goal-loop.ts +11 -8
- package/src/pantheon/task-result-guard.ts +50 -14
- package/src/pantheon/v2-execute-after.ts +135 -24
- package/src/pantheon/v2-tools.ts +10 -1
- package/src/plugin-v2.ts +6 -4
- package/src/plugin.ts +3 -2
- package/src/plugins/tui/dist/tui-v2.js +2 -2
- package/src/plugins/tui/dist/tui.js +1 -1
- package/src/plugins/tui/package-lock.json +2 -2
- package/src/plugins/tui/package.json +1 -1
- package/src/routing.yml +4 -4
- package/src/skills/codemap/SKILL.md +1 -1
- package/src/skills/memory-bank/SKILL.md +17 -13
- package/src/skills/session-goal/SKILL.md +12 -22
- package/scripts/probe-context-rehydrate.mjs +0 -263
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
#!/usr/bin/env python3
|
|
2
2
|
"""Pantheon Persistence MCP Server.
|
|
3
3
|
|
|
4
|
-
|
|
5
|
-
|
|
4
|
+
Operational-state checkpoints and manual session-scoped goal tools. The server
|
|
5
|
+
exposes context_save/context_get for checkpoints and four manual goal tools.
|
|
6
|
+
Goal tools use OpenCode session metadata and do not trigger automatic continuation.
|
|
6
7
|
|
|
7
8
|
Usage:
|
|
8
|
-
|
|
9
|
+
<venv>/bin/python3 scripts/mcp_persistence.py
|
|
9
10
|
"""
|
|
10
11
|
|
|
11
12
|
from __future__ import annotations
|
|
@@ -18,14 +19,17 @@ import sqlite3
|
|
|
18
19
|
import sys
|
|
19
20
|
import threading
|
|
20
21
|
import time
|
|
21
|
-
from collections.abc import
|
|
22
|
-
from contextlib import suppress
|
|
22
|
+
from collections.abc import Iterator, Mapping
|
|
23
|
+
from contextlib import contextmanager, suppress
|
|
24
|
+
from dataclasses import dataclass
|
|
23
25
|
from datetime import UTC, datetime, timedelta
|
|
24
26
|
from pathlib import Path
|
|
25
|
-
from typing import Annotated
|
|
27
|
+
from typing import Annotated, Literal
|
|
28
|
+
from uuid import uuid4
|
|
26
29
|
|
|
27
|
-
from _pantheon_paths import pantheon_home
|
|
28
|
-
from fastmcp import FastMCP
|
|
30
|
+
from _pantheon_paths import pantheon_home
|
|
31
|
+
from fastmcp import Context, FastMCP
|
|
32
|
+
from fastmcp.exceptions import ToolError
|
|
29
33
|
from pydantic import Field
|
|
30
34
|
|
|
31
35
|
# ── Schema ──────────────────────────────────────────────────────────────────────
|
|
@@ -37,7 +41,7 @@ CREATE TABLE IF NOT EXISTS kv_store (
|
|
|
37
41
|
key TEXT NOT NULL,
|
|
38
42
|
value TEXT NOT NULL,
|
|
39
43
|
expires_at TEXT, -- ISO 8601, NULL = forever
|
|
40
|
-
deleted_at TEXT, -- NULL = active
|
|
44
|
+
deleted_at TEXT, -- NULL = active; retained for legacy schema compatibility
|
|
41
45
|
created_at TEXT NOT NULL DEFAULT (datetime('now')),
|
|
42
46
|
updated_at TEXT NOT NULL DEFAULT (datetime('now')),
|
|
43
47
|
revision INTEGER, -- context monotonic revision; NULL = legacy row
|
|
@@ -83,16 +87,15 @@ END;
|
|
|
83
87
|
|
|
84
88
|
mcp = FastMCP(
|
|
85
89
|
"pantheon-persistence",
|
|
86
|
-
instructions="
|
|
87
|
-
"
|
|
90
|
+
instructions="Operational-state checkpoints through context_save/context_get "
|
|
91
|
+
"and four manual session-scoped goal tools. Goal tools use OpenCode session "
|
|
92
|
+
"metadata and do not trigger automatic continuation.",
|
|
88
93
|
)
|
|
89
94
|
|
|
90
95
|
# ── Database Initialization ─────────────────────────────────────────────────────
|
|
91
96
|
|
|
92
97
|
_global_db: sqlite3.Connection | None = None
|
|
93
98
|
_project_db: sqlite3.Connection | None = None
|
|
94
|
-
_DELETELOG_MAX_BYTES: int = 1_048_576 # 1 MB
|
|
95
|
-
_DELETELOG_KEEP: int = 3
|
|
96
99
|
|
|
97
100
|
|
|
98
101
|
def _init_db(db_path: Path) -> sqlite3.Connection:
|
|
@@ -103,11 +106,13 @@ def _init_db(db_path: Path) -> sqlite3.Connection:
|
|
|
103
106
|
conn.execute("PRAGMA busy_timeout=5000")
|
|
104
107
|
conn.execute("PRAGMA foreign_keys=ON")
|
|
105
108
|
# ── FTS5 Availability Check ──────────────────────────────────────────
|
|
106
|
-
# Check BEFORE schema creation.
|
|
109
|
+
# Check BEFORE schema creation. FTS5 is an optional internal index.
|
|
107
110
|
row = conn.execute("PRAGMA compile_options").fetchall()
|
|
108
111
|
if not any("ENABLE_FTS5" in r[0] for r in row):
|
|
109
112
|
print(
|
|
110
|
-
"WARNING: SQLite FTS5
|
|
113
|
+
"WARNING: SQLite FTS5 unavailable; the internal full-text index "
|
|
114
|
+
"was not initialized.",
|
|
115
|
+
file=sys.stderr,
|
|
111
116
|
)
|
|
112
117
|
import re as _re # noqa: PLC0415
|
|
113
118
|
|
|
@@ -163,462 +168,1243 @@ def _db(scope: str) -> sqlite3.Connection:
|
|
|
163
168
|
raise ValueError(f"Unknown scope: {scope!r}. Expected 'global' or 'project'.")
|
|
164
169
|
|
|
165
170
|
|
|
166
|
-
# ──
|
|
171
|
+
# ── Typed, session-scoped manual goal repository ────────────────────────────────
|
|
167
172
|
|
|
173
|
+
GOAL_SCHEMA_VERSION = 1
|
|
174
|
+
GOAL_SCHEMA_MIGRATION_COMMAND = "<venv-python> <installed-script> --migrate-goals"
|
|
175
|
+
GOAL_SCHEMA_MIGRATION_COMMAND_GUIDANCE = (
|
|
176
|
+
"Global install: <runtime>/.venv/bin/python3 "
|
|
177
|
+
"<runtime>/scripts/mcp_persistence.py --migrate-goals. "
|
|
178
|
+
"Project install: <project>/.venv/bin/python3 "
|
|
179
|
+
"<project>/.opencode/scripts/mcp_persistence.py --migrate-goals. "
|
|
180
|
+
"The simplest reliable source of truth is command[0] in opencode.json "
|
|
181
|
+
"for pantheon-persistence."
|
|
182
|
+
)
|
|
183
|
+
GOAL_TITLE_MAX_LENGTH = 512
|
|
184
|
+
GOAL_DESCRIPTION_MAX_LENGTH = 16_384
|
|
185
|
+
GOAL_SESSION_ID_MAX_LENGTH = 128
|
|
186
|
+
GOAL_ID_MAX_LENGTH = 64
|
|
187
|
+
GOAL_VERSION_MAX = 9_223_372_036_854_775_807
|
|
188
|
+
DELETE_CODEPOINT = 127
|
|
189
|
+
_DESCRIPTION_ALLOWED_CONTROLS = {"\t", "\n", "\r"}
|
|
190
|
+
GoalStatus = Literal["active", "done"]
|
|
191
|
+
_goal_write_lock = threading.RLock()
|
|
168
192
|
|
|
169
|
-
def _rotate_deletelog(log_path: Path) -> None:
|
|
170
|
-
"""Rotate deletelog at 1MB, keep last 3 rotated files."""
|
|
171
|
-
if not log_path.exists() or log_path.stat().st_size < _DELETELOG_MAX_BYTES:
|
|
172
|
-
return
|
|
173
193
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
if older.exists():
|
|
178
|
-
if i == _DELETELOG_KEEP:
|
|
179
|
-
older.unlink()
|
|
180
|
-
else:
|
|
181
|
-
older.rename(log_path.with_suffix(f".deletelog.{i + 1}"))
|
|
194
|
+
@dataclass(frozen=True, slots=True)
|
|
195
|
+
class GoalRecord:
|
|
196
|
+
"""A manual goal persisted in the Persistence deployment database."""
|
|
182
197
|
|
|
183
|
-
|
|
184
|
-
|
|
198
|
+
goal_id: str
|
|
199
|
+
session_id: str
|
|
200
|
+
title: str
|
|
201
|
+
description: str | None
|
|
202
|
+
status: GoalStatus
|
|
203
|
+
created_at: str
|
|
204
|
+
updated_at: str
|
|
205
|
+
version: int
|
|
185
206
|
|
|
186
207
|
|
|
187
|
-
|
|
188
|
-
"""
|
|
189
|
-
log_path = db_path.with_name(db_path.name + ".deletelog")
|
|
190
|
-
_rotate_deletelog(log_path)
|
|
208
|
+
class GoalStoreError(Exception):
|
|
209
|
+
"""Base error for the typed manual-goal repository API."""
|
|
191
210
|
|
|
192
|
-
timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
|
|
193
|
-
keys_str = ",".join(keys)
|
|
194
|
-
with open(log_path, "a", encoding="utf-8") as f:
|
|
195
|
-
f.write(f"[{timestamp}] PURGED={count} KEYS=[{keys_str}]\n")
|
|
196
211
|
|
|
212
|
+
class GoalSchemaNotInitializedError(GoalStoreError):
|
|
213
|
+
"""Raised when goal operations target a DB without the goal schema."""
|
|
197
214
|
|
|
198
|
-
# ── Resolve scope and init databases ────────────────────────────────────────────
|
|
199
215
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
parser.add_argument("--project-db", default=None)
|
|
203
|
-
args = parser.parse_args()
|
|
216
|
+
class GoalSchemaVersionError(GoalStoreError):
|
|
217
|
+
"""Raised for an unsupported or inconsistent goal schema migration version."""
|
|
204
218
|
|
|
205
|
-
_global_root = (
|
|
206
|
-
Path(args.global_db) if args.global_db else pantheon_home() / "persistence"
|
|
207
|
-
)
|
|
208
|
-
_global_db = _init_db(_global_root / "global.db")
|
|
209
219
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
if args.project_db:
|
|
213
|
-
_project_db_path = Path(args.project_db)
|
|
214
|
-
_project_db_instance = _init_db(_project_db_path)
|
|
215
|
-
else:
|
|
216
|
-
_proj = pantheon_project()
|
|
217
|
-
if _proj:
|
|
218
|
-
_project_db_path = _proj / ".pantheon" / "persistence" / "project.db"
|
|
219
|
-
_project_db_instance = _init_db(_project_db_path)
|
|
220
|
-
_project_db = _project_db_instance
|
|
220
|
+
class GoalValidationError(GoalStoreError, ValueError):
|
|
221
|
+
"""Raised when a goal field or expected version is invalid."""
|
|
221
222
|
|
|
222
223
|
|
|
223
|
-
|
|
224
|
+
class ActiveGoalExistsError(GoalStoreError):
|
|
225
|
+
"""Raised when a session already has an active goal."""
|
|
224
226
|
|
|
225
227
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
description="Store a key-value pair in a namespace with optional TTL (seconds). "
|
|
229
|
-
"INSERT OR REPLACE on duplicate (namespace, key). "
|
|
230
|
-
"ttl must be an integer between 1 and 31536000, or null/omitted. "
|
|
231
|
-
"All invalid arguments are reported together in one message.",
|
|
232
|
-
)
|
|
233
|
-
async def kv_store(
|
|
234
|
-
namespace: str,
|
|
235
|
-
key: str,
|
|
236
|
-
value: str,
|
|
237
|
-
ttl: int | None = None,
|
|
238
|
-
scope: str = "project",
|
|
239
|
-
) -> dict:
|
|
240
|
-
"""Store a value under namespace+key with optional TTL.
|
|
228
|
+
class GoalNotFoundError(GoalStoreError, LookupError):
|
|
229
|
+
"""Raised when an update/done targets no goal owned by the session."""
|
|
241
230
|
|
|
242
|
-
Validates every argument before writing so a caller with both a bad ttl
|
|
243
|
-
and a bad scope sees both violations in one message.
|
|
244
231
|
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
key: Unique key within the namespace.
|
|
248
|
-
value: String value to store.
|
|
249
|
-
ttl: Time-to-live in seconds (None = forever).
|
|
250
|
-
scope: 'project' (default) or 'global'.
|
|
232
|
+
class GoalVersionConflictError(GoalStoreError):
|
|
233
|
+
"""Raised when an optimistic update uses a stale version."""
|
|
251
234
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
"""
|
|
255
|
-
|
|
235
|
+
|
|
236
|
+
class GoalStorageError(GoalStoreError):
|
|
237
|
+
"""Raised for SQLite errors or an invalid transaction state."""
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
class GoalBackupRetainedError(GoalStorageError):
|
|
241
|
+
"""Raised when an upgrade fails after its verified backup was retained."""
|
|
242
|
+
|
|
243
|
+
def __init__(self, backup_path: Path, cause: Exception) -> None:
|
|
244
|
+
self.backup_path = backup_path
|
|
245
|
+
super().__init__(
|
|
246
|
+
f"goal schema upgrade failed after backup verification: {cause}"
|
|
247
|
+
)
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
class _GoalUnset:
|
|
251
|
+
"""Sentinel distinguishing an omitted field from clearing description."""
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
_GOAL_UNSET = _GoalUnset()
|
|
255
|
+
|
|
256
|
+
|
|
257
|
+
def _assert_project_goal_connection(
|
|
258
|
+
conn: sqlite3.Connection,
|
|
259
|
+
expected_path: str | Path | None,
|
|
260
|
+
*,
|
|
261
|
+
explicit_project_db: bool = False,
|
|
262
|
+
) -> None:
|
|
263
|
+
"""Reject connections outside this server's Persistence database."""
|
|
264
|
+
if expected_path is None:
|
|
265
|
+
raise GoalSchemaNotInitializedError(
|
|
266
|
+
"goal operations require this server's Persistence database"
|
|
267
|
+
)
|
|
268
|
+
project_path = Path(expected_path).expanduser().resolve()
|
|
269
|
+
if not explicit_project_db:
|
|
270
|
+
server_path = _resolve_project_db_path()
|
|
271
|
+
if project_path != server_path:
|
|
272
|
+
raise GoalSchemaNotInitializedError(
|
|
273
|
+
"migration target differs from the Persistence server database "
|
|
274
|
+
f"({server_path}); stop the server and rerun with --project-db "
|
|
275
|
+
"only when the explicitly selected database is intended"
|
|
276
|
+
)
|
|
256
277
|
try:
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
278
|
+
with _goal_write_lock:
|
|
279
|
+
databases = conn.execute("PRAGMA database_list").fetchall()
|
|
280
|
+
except sqlite3.Error as exc:
|
|
281
|
+
raise GoalStorageError("could not verify Persistence database") from exc
|
|
282
|
+
main_path = next((row[2] for row in databases if row[1] == "main"), "")
|
|
283
|
+
if not main_path or Path(main_path).resolve() != project_path:
|
|
284
|
+
raise GoalSchemaNotInitializedError(
|
|
285
|
+
"goal operations are restricted to this server's Persistence database"
|
|
286
|
+
)
|
|
287
|
+
try:
|
|
288
|
+
has_kv_store = conn.execute(
|
|
289
|
+
"SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'kv_store'"
|
|
290
|
+
).fetchone()
|
|
291
|
+
except sqlite3.Error as exc:
|
|
292
|
+
raise GoalStorageError("could not verify Persistence database schema") from exc
|
|
293
|
+
if has_kv_store is None:
|
|
294
|
+
raise GoalSchemaNotInitializedError(
|
|
295
|
+
"goal operations require an existing Pantheon Persistence database; "
|
|
296
|
+
"ask the user to start the server once first"
|
|
297
|
+
)
|
|
264
298
|
|
|
265
|
-
conn = _db(scope)
|
|
266
|
-
expires_at: str | None = None
|
|
267
|
-
if validated_ttl is not None:
|
|
268
|
-
expires_at = (datetime.now(UTC) + timedelta(seconds=validated_ttl)).isoformat()
|
|
269
299
|
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
300
|
+
def _project_goal_connection() -> sqlite3.Connection:
|
|
301
|
+
conn = globals().get("_project_db")
|
|
302
|
+
if conn is None:
|
|
303
|
+
raise GoalSchemaNotInitializedError(
|
|
304
|
+
"goal operations require this server's Persistence database"
|
|
305
|
+
)
|
|
306
|
+
_assert_project_goal_connection(
|
|
307
|
+
conn,
|
|
308
|
+
globals().get("_project_db_path"),
|
|
309
|
+
explicit_project_db=globals().get("_project_db_explicit", False),
|
|
278
310
|
)
|
|
279
|
-
conn
|
|
311
|
+
return conn
|
|
280
312
|
|
|
281
|
-
# Opportunistic auto-purge: if namespace has >500 entries, purge expired
|
|
282
|
-
_opportunistic_auto_purge(conn, namespace)
|
|
283
313
|
|
|
284
|
-
|
|
314
|
+
@contextmanager
|
|
315
|
+
def _goal_transaction(conn: sqlite3.Connection) -> Iterator[None]:
|
|
316
|
+
"""Serialize same-process use and acquire SQLite's cross-process write lock."""
|
|
317
|
+
with _goal_write_lock:
|
|
318
|
+
if conn.in_transaction:
|
|
319
|
+
raise GoalStorageError("goal connection already has an active transaction")
|
|
320
|
+
try:
|
|
321
|
+
conn.execute("BEGIN IMMEDIATE")
|
|
322
|
+
except sqlite3.Error as exc:
|
|
323
|
+
raise GoalStorageError("could not begin goal transaction") from exc
|
|
324
|
+
try:
|
|
325
|
+
yield
|
|
326
|
+
conn.commit()
|
|
327
|
+
except BaseException:
|
|
328
|
+
with suppress(sqlite3.Error):
|
|
329
|
+
conn.rollback()
|
|
330
|
+
raise
|
|
285
331
|
|
|
286
332
|
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
333
|
+
def upgrade_goal_schema(
|
|
334
|
+
conn: sqlite3.Connection,
|
|
335
|
+
expected_path: str | Path | None = None,
|
|
336
|
+
*,
|
|
337
|
+
explicit_project_db: bool | None = None,
|
|
338
|
+
) -> None:
|
|
339
|
+
"""Apply goal schema upgrades to the explicitly supplied Persistence DB."""
|
|
340
|
+
_assert_project_goal_connection(
|
|
341
|
+
conn,
|
|
342
|
+
expected_path or globals().get("_project_db_path"),
|
|
343
|
+
explicit_project_db=(
|
|
344
|
+
globals().get("_project_db_explicit", False)
|
|
345
|
+
if explicit_project_db is None
|
|
346
|
+
else explicit_project_db
|
|
347
|
+
),
|
|
348
|
+
)
|
|
349
|
+
try:
|
|
350
|
+
with _goal_transaction(conn):
|
|
351
|
+
current = _inspect_goal_schema_version(conn)
|
|
352
|
+
if current == GOAL_SCHEMA_VERSION:
|
|
353
|
+
return
|
|
354
|
+
conn.execute(
|
|
355
|
+
"CREATE TABLE IF NOT EXISTS pantheon_goal_schema_migrations ("
|
|
356
|
+
"version INTEGER PRIMARY KEY CHECK (version > 0), "
|
|
357
|
+
"applied_at TEXT NOT NULL)"
|
|
358
|
+
)
|
|
359
|
+
conn.execute(
|
|
360
|
+
"CREATE TABLE pantheon_goals ("
|
|
361
|
+
"goal_id TEXT PRIMARY KEY NOT NULL, "
|
|
362
|
+
"session_id TEXT NOT NULL CHECK ("
|
|
363
|
+
"length(trim(session_id)) BETWEEN 1 AND 128 AND "
|
|
364
|
+
"session_id = trim(session_id)), "
|
|
365
|
+
"title TEXT NOT NULL CHECK ("
|
|
366
|
+
"length(title) BETWEEN 1 AND 512 AND length(trim(title)) > 0), "
|
|
367
|
+
"description TEXT CHECK (description IS NULL OR "
|
|
368
|
+
"length(description) <= 16384), "
|
|
369
|
+
"status TEXT NOT NULL CHECK (status IN ('active', 'done')), "
|
|
370
|
+
"created_at TEXT NOT NULL, updated_at TEXT NOT NULL, "
|
|
371
|
+
"version INTEGER NOT NULL CHECK (version > 0))"
|
|
372
|
+
)
|
|
373
|
+
conn.execute(
|
|
374
|
+
"CREATE UNIQUE INDEX uq_pantheon_goals_active_session "
|
|
375
|
+
"ON pantheon_goals(session_id) WHERE status = 'active'"
|
|
376
|
+
)
|
|
377
|
+
conn.execute(
|
|
378
|
+
"CREATE INDEX idx_pantheon_goals_session_history "
|
|
379
|
+
"ON pantheon_goals(session_id, created_at DESC, goal_id DESC)"
|
|
380
|
+
)
|
|
381
|
+
conn.execute(
|
|
382
|
+
"INSERT INTO pantheon_goal_schema_migrations(version, applied_at) "
|
|
383
|
+
"VALUES (?, ?)",
|
|
384
|
+
(GOAL_SCHEMA_VERSION, _goal_timestamp()),
|
|
385
|
+
)
|
|
386
|
+
except sqlite3.Error as exc:
|
|
387
|
+
raise GoalStorageError("could not upgrade Persistence goal schema") from exc
|
|
298
388
|
|
|
299
|
-
Args:
|
|
300
|
-
namespace: Logical grouping for keys.
|
|
301
|
-
key: Unique key within the namespace.
|
|
302
|
-
scope: 'project' (default) or 'global'.
|
|
303
389
|
|
|
304
|
-
|
|
305
|
-
|
|
390
|
+
def downgrade_goal_schema(
|
|
391
|
+
conn: sqlite3.Connection,
|
|
392
|
+
target_version: int = 0,
|
|
393
|
+
*,
|
|
394
|
+
expected_path: str | Path | None = None,
|
|
395
|
+
explicit_project_db: bool | None = None,
|
|
396
|
+
) -> None:
|
|
397
|
+
"""Drop an empty goal schema; refuse rollback when goal data would be lost.
|
|
398
|
+
|
|
399
|
+
Populated goal schemas are intentionally irreversible through this helper:
|
|
400
|
+
callers must preserve/export their data before using any external teardown.
|
|
306
401
|
"""
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
402
|
+
_assert_project_goal_connection(
|
|
403
|
+
conn,
|
|
404
|
+
expected_path or globals().get("_project_db_path"),
|
|
405
|
+
explicit_project_db=(
|
|
406
|
+
globals().get("_project_db_explicit", False)
|
|
407
|
+
if explicit_project_db is None
|
|
408
|
+
else explicit_project_db
|
|
409
|
+
),
|
|
410
|
+
)
|
|
411
|
+
if (
|
|
412
|
+
isinstance(target_version, bool)
|
|
413
|
+
or not isinstance(target_version, int)
|
|
414
|
+
or target_version != 0
|
|
415
|
+
):
|
|
416
|
+
raise GoalSchemaVersionError(
|
|
417
|
+
"only downgrade to goal schema version 0 is supported"
|
|
418
|
+
)
|
|
419
|
+
try:
|
|
420
|
+
with _goal_transaction(conn):
|
|
421
|
+
exists = conn.execute(
|
|
422
|
+
"SELECT 1 FROM sqlite_master WHERE type = 'table' "
|
|
423
|
+
"AND name = 'pantheon_goal_schema_migrations'"
|
|
424
|
+
).fetchone()
|
|
425
|
+
if exists is None:
|
|
426
|
+
return
|
|
427
|
+
row = conn.execute(
|
|
428
|
+
"SELECT COALESCE(MAX(version), 0) FROM pantheon_goal_schema_migrations"
|
|
429
|
+
).fetchone()
|
|
430
|
+
current = int(row[0])
|
|
431
|
+
if current > GOAL_SCHEMA_VERSION:
|
|
432
|
+
raise GoalSchemaVersionError(
|
|
433
|
+
f"cannot downgrade unsupported goal schema version {current}"
|
|
434
|
+
)
|
|
435
|
+
goals_exist = conn.execute(
|
|
436
|
+
"SELECT 1 FROM sqlite_master WHERE type = 'table' "
|
|
437
|
+
"AND name = 'pantheon_goals'"
|
|
438
|
+
).fetchone()
|
|
439
|
+
if (
|
|
440
|
+
goals_exist is not None
|
|
441
|
+
and conn.execute("SELECT 1 FROM pantheon_goals LIMIT 1").fetchone()
|
|
442
|
+
is not None
|
|
443
|
+
):
|
|
444
|
+
raise GoalSchemaVersionError(
|
|
445
|
+
"cannot downgrade goal schema while goal data exists; "
|
|
446
|
+
"preserve or export goals before removing the schema"
|
|
447
|
+
)
|
|
448
|
+
conn.execute("DROP INDEX IF EXISTS uq_pantheon_goals_active_session")
|
|
449
|
+
conn.execute("DROP INDEX IF EXISTS idx_pantheon_goals_session_history")
|
|
450
|
+
conn.execute("DROP TABLE IF EXISTS pantheon_goals")
|
|
451
|
+
conn.execute("DROP TABLE pantheon_goal_schema_migrations")
|
|
452
|
+
except sqlite3.Error as exc:
|
|
453
|
+
raise GoalStorageError("could not downgrade goal schema") from exc
|
|
316
454
|
|
|
317
455
|
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
description=(
|
|
321
|
-
"Return storage statistics: total entries, expired count, per-namespace "
|
|
322
|
-
"breakdown, DB file size."
|
|
323
|
-
),
|
|
324
|
-
)
|
|
325
|
-
async def kv_stats(
|
|
326
|
-
scope: str = "project",
|
|
327
|
-
) -> dict:
|
|
328
|
-
"""Return storage statistics for the given scope.
|
|
456
|
+
def _goal_timestamp() -> str:
|
|
457
|
+
return datetime.now(UTC).isoformat(timespec="microseconds")
|
|
329
458
|
|
|
330
|
-
Args:
|
|
331
|
-
scope: 'project' (default) or 'global'.
|
|
332
459
|
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
460
|
+
def _validate_goal_session_id(session_id: str) -> str:
|
|
461
|
+
if not isinstance(session_id, str) or not session_id:
|
|
462
|
+
raise GoalValidationError("session_id must be a non-empty string")
|
|
463
|
+
if len(session_id) > GOAL_SESSION_ID_MAX_LENGTH:
|
|
464
|
+
raise GoalValidationError(
|
|
465
|
+
f"session_id exceeds the {GOAL_SESSION_ID_MAX_LENGTH}-character limit"
|
|
466
|
+
)
|
|
467
|
+
if session_id != session_id.strip() or any(
|
|
468
|
+
ord(char) < MIN_PRINTABLE_CODEPOINT or char == chr(DELETE_CODEPOINT)
|
|
469
|
+
for char in session_id
|
|
470
|
+
):
|
|
471
|
+
raise GoalValidationError(
|
|
472
|
+
"session_id contains whitespace or a control character"
|
|
473
|
+
)
|
|
474
|
+
return session_id
|
|
337
475
|
|
|
338
|
-
total = conn.execute(
|
|
339
|
-
"SELECT COUNT(*) FROM kv_store WHERE deleted_at IS NULL"
|
|
340
|
-
).fetchone()[0]
|
|
341
|
-
expired = conn.execute(
|
|
342
|
-
"SELECT COUNT(*) FROM kv_store "
|
|
343
|
-
"WHERE expires_at IS NOT NULL AND julianday(expires_at) < julianday('now') "
|
|
344
|
-
"AND deleted_at IS NULL"
|
|
345
|
-
).fetchone()[0]
|
|
346
|
-
|
|
347
|
-
ns_rows = conn.execute(
|
|
348
|
-
"SELECT namespace, COUNT(*) as cnt, "
|
|
349
|
-
"SUM(CASE WHEN expires_at IS NOT NULL AND julianday(expires_at) "
|
|
350
|
-
"< julianday('now') THEN 1 ELSE 0 END) as expired_count "
|
|
351
|
-
"FROM kv_store WHERE deleted_at IS NULL GROUP BY namespace ORDER BY cnt DESC"
|
|
352
|
-
).fetchall()
|
|
353
476
|
|
|
354
|
-
|
|
477
|
+
def _validate_goal_text(
|
|
478
|
+
value: object, field: str, limit: int, *, allow_newlines: bool = False
|
|
479
|
+
) -> str:
|
|
480
|
+
if not isinstance(value, str):
|
|
481
|
+
raise GoalValidationError(f"{field} must be a string")
|
|
482
|
+
if len(value) > limit:
|
|
483
|
+
raise GoalValidationError(f"{field} exceeds the {limit}-character limit")
|
|
484
|
+
if field == "title" and not value.strip():
|
|
485
|
+
raise GoalValidationError("title must be a non-empty string")
|
|
486
|
+
if any(
|
|
487
|
+
(
|
|
488
|
+
ord(char) < MIN_PRINTABLE_CODEPOINT
|
|
489
|
+
and not (allow_newlines and char in _DESCRIPTION_ALLOWED_CONTROLS)
|
|
490
|
+
)
|
|
491
|
+
or char == chr(DELETE_CODEPOINT)
|
|
492
|
+
for char in value
|
|
493
|
+
):
|
|
494
|
+
raise GoalValidationError(f"{field} contains a control character")
|
|
495
|
+
return value
|
|
355
496
|
|
|
356
|
-
db_path = _resolve_db_path(scope)
|
|
357
|
-
db_size = db_path.stat().st_size if db_path and db_path.exists() else 0
|
|
358
497
|
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
498
|
+
def _validate_goal_version(version: int) -> int:
|
|
499
|
+
if (
|
|
500
|
+
isinstance(version, bool)
|
|
501
|
+
or not isinstance(version, int)
|
|
502
|
+
or version < 1
|
|
503
|
+
or version > GOAL_VERSION_MAX
|
|
504
|
+
):
|
|
505
|
+
raise GoalValidationError(
|
|
506
|
+
f"expected_version must be an integer from 1 to {GOAL_VERSION_MAX}"
|
|
507
|
+
)
|
|
508
|
+
return version
|
|
366
509
|
|
|
367
510
|
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
)
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
)
|
|
378
|
-
|
|
511
|
+
def _validate_goal_id(goal_id: str) -> str:
|
|
512
|
+
if (
|
|
513
|
+
not isinstance(goal_id, str)
|
|
514
|
+
or not goal_id
|
|
515
|
+
or len(goal_id) > GOAL_ID_MAX_LENGTH
|
|
516
|
+
or any(
|
|
517
|
+
ord(char) < MIN_PRINTABLE_CODEPOINT or char == chr(DELETE_CODEPOINT)
|
|
518
|
+
for char in goal_id
|
|
519
|
+
)
|
|
520
|
+
):
|
|
521
|
+
raise GoalValidationError(
|
|
522
|
+
f"goal_id must be a valid string of at most {GOAL_ID_MAX_LENGTH} chars"
|
|
523
|
+
)
|
|
524
|
+
return goal_id
|
|
379
525
|
|
|
380
|
-
Args:
|
|
381
|
-
namespace: Logical grouping for keys.
|
|
382
|
-
key: Unique key within the namespace.
|
|
383
|
-
scope: 'project' (default) or 'global'.
|
|
384
526
|
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
527
|
+
def _inspect_goal_schema_version(conn: sqlite3.Connection) -> int | None:
|
|
528
|
+
"""Read and validate the goal schema version without changing the DB."""
|
|
529
|
+
try:
|
|
530
|
+
tables = {
|
|
531
|
+
row[0]
|
|
532
|
+
for row in conn.execute(
|
|
533
|
+
"SELECT name FROM sqlite_master WHERE type = 'table' "
|
|
534
|
+
"AND name IN ('pantheon_goals', 'pantheon_goal_schema_migrations')"
|
|
535
|
+
)
|
|
536
|
+
}
|
|
537
|
+
has_goals = "pantheon_goals" in tables
|
|
538
|
+
has_migrations = "pantheon_goal_schema_migrations" in tables
|
|
539
|
+
if not has_migrations:
|
|
540
|
+
if has_goals:
|
|
541
|
+
raise GoalSchemaVersionError(
|
|
542
|
+
"pantheon_goals exists without goal schema migration history"
|
|
543
|
+
)
|
|
544
|
+
return None
|
|
545
|
+
row = conn.execute(
|
|
546
|
+
"SELECT MAX(version) FROM pantheon_goal_schema_migrations"
|
|
547
|
+
).fetchone()
|
|
548
|
+
current = int(row[0] or 0)
|
|
549
|
+
if current == 0:
|
|
550
|
+
if has_goals:
|
|
551
|
+
raise GoalSchemaVersionError(
|
|
552
|
+
"pantheon_goals exists without a recorded schema version"
|
|
553
|
+
)
|
|
554
|
+
return None
|
|
555
|
+
if current > GOAL_SCHEMA_VERSION:
|
|
556
|
+
raise GoalSchemaVersionError(
|
|
557
|
+
f"goal schema version {current} is newer than supported "
|
|
558
|
+
f"version {GOAL_SCHEMA_VERSION}"
|
|
559
|
+
)
|
|
560
|
+
if current < GOAL_SCHEMA_VERSION:
|
|
561
|
+
raise GoalSchemaVersionError(
|
|
562
|
+
f"goal schema version {current} is older than supported "
|
|
563
|
+
f"version {GOAL_SCHEMA_VERSION}"
|
|
564
|
+
)
|
|
565
|
+
if not has_goals:
|
|
566
|
+
raise GoalSchemaVersionError(
|
|
567
|
+
"goal schema migration history exists but pantheon_goals is missing; "
|
|
568
|
+
"this is a half-created schema. Ask the user to preserve the current "
|
|
569
|
+
"database, restore a verified backup or recover the missing schema, "
|
|
570
|
+
"then rerun the human-approved migration."
|
|
571
|
+
)
|
|
572
|
+
indexes = {
|
|
573
|
+
row[0]
|
|
574
|
+
for row in conn.execute(
|
|
575
|
+
"SELECT name FROM sqlite_master WHERE type = 'index' "
|
|
576
|
+
"AND tbl_name = 'pantheon_goals'"
|
|
577
|
+
)
|
|
578
|
+
}
|
|
579
|
+
expected = {
|
|
580
|
+
"uq_pantheon_goals_active_session",
|
|
581
|
+
"idx_pantheon_goals_session_history",
|
|
582
|
+
}
|
|
583
|
+
if not expected.issubset(indexes):
|
|
584
|
+
raise GoalSchemaVersionError(
|
|
585
|
+
"goal schema migration history exists but required indexes are missing"
|
|
586
|
+
)
|
|
587
|
+
return current
|
|
588
|
+
except sqlite3.Error as exc:
|
|
589
|
+
raise GoalStorageError("could not inspect goal schema version") from exc
|
|
590
|
+
|
|
591
|
+
|
|
592
|
+
def _require_goal_schema(conn: sqlite3.Connection) -> None:
|
|
593
|
+
current = _inspect_goal_schema_version(conn)
|
|
594
|
+
if current is None:
|
|
595
|
+
raise GoalSchemaNotInitializedError(
|
|
596
|
+
"goal schema is not initialized. Ask the user to run "
|
|
597
|
+
f"`{GOAL_SCHEMA_MIGRATION_COMMAND}`; goal schema migration is a "
|
|
598
|
+
"human-approved operation. "
|
|
599
|
+
f"{GOAL_SCHEMA_MIGRATION_COMMAND_GUIDANCE}"
|
|
600
|
+
)
|
|
601
|
+
|
|
602
|
+
|
|
603
|
+
def _raw_goal_schema_version(conn: sqlite3.Connection) -> int:
|
|
604
|
+
"""Read the recorded version for backup verification, without validation."""
|
|
605
|
+
try:
|
|
606
|
+
exists = conn.execute(
|
|
607
|
+
"SELECT 1 FROM sqlite_master WHERE type = 'table' "
|
|
608
|
+
"AND name = 'pantheon_goal_schema_migrations'"
|
|
609
|
+
).fetchone()
|
|
610
|
+
except sqlite3.Error as exc:
|
|
611
|
+
raise GoalStorageError("could not inspect goal schema version") from exc
|
|
612
|
+
if exists is None:
|
|
613
|
+
return 0
|
|
614
|
+
try:
|
|
615
|
+
row = conn.execute(
|
|
616
|
+
"SELECT MAX(version) FROM pantheon_goal_schema_migrations"
|
|
617
|
+
).fetchone()
|
|
618
|
+
except sqlite3.Error as exc:
|
|
619
|
+
raise GoalStorageError("could not read goal schema version") from exc
|
|
620
|
+
return int(row[0] or 0)
|
|
621
|
+
|
|
622
|
+
|
|
623
|
+
def _resolve_project_db_path(project_db: str | Path | None = None) -> Path:
|
|
624
|
+
"""Resolve explicit CLI path, project override, then runtime target."""
|
|
625
|
+
if project_db is not None:
|
|
626
|
+
path = Path(project_db).expanduser()
|
|
627
|
+
if not path.is_absolute():
|
|
628
|
+
path = Path(__file__).resolve().parents[1] / path
|
|
629
|
+
return path.resolve()
|
|
630
|
+
configured_project = os.environ.get("PANTHEON_PROJECT")
|
|
631
|
+
if configured_project:
|
|
632
|
+
project_root = Path(configured_project)
|
|
633
|
+
if not project_root.is_absolute():
|
|
634
|
+
raise GoalSchemaNotInitializedError(
|
|
635
|
+
"PANTHEON_PROJECT must be an absolute path; set it to the "
|
|
636
|
+
"absolute project root or unset it."
|
|
637
|
+
)
|
|
638
|
+
return (project_root / ".pantheon" / "persistence" / "project.db").resolve()
|
|
639
|
+
project_root = Path(__file__).resolve().parents[1]
|
|
640
|
+
return (project_root / ".pantheon" / "persistence" / "project.db").resolve()
|
|
641
|
+
|
|
642
|
+
|
|
643
|
+
def _goal_dry_run_file_metadata(
|
|
644
|
+
db_path: Path,
|
|
645
|
+
) -> tuple[os.stat_result | None, os.stat_result | None, os.stat_result | None]:
|
|
646
|
+
def optional_stat(path: Path) -> os.stat_result | None:
|
|
647
|
+
try:
|
|
648
|
+
return path.stat()
|
|
649
|
+
except FileNotFoundError:
|
|
650
|
+
return None
|
|
651
|
+
|
|
652
|
+
return (
|
|
653
|
+
optional_stat(db_path),
|
|
654
|
+
optional_stat(db_path.with_name(db_path.name + "-wal")),
|
|
655
|
+
optional_stat(db_path.with_name(db_path.name + "-shm")),
|
|
392
656
|
)
|
|
393
|
-
conn.commit()
|
|
394
|
-
if cursor.rowcount > 0:
|
|
395
|
-
return {"status": "deleted"}
|
|
396
|
-
return {"status": "not_found"}
|
|
397
657
|
|
|
398
658
|
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
description="List keys in a namespace with optional prefix filter. "
|
|
402
|
-
"Returns up to 'limit' entries (default 100).",
|
|
403
|
-
)
|
|
404
|
-
async def kv_list(
|
|
405
|
-
namespace: str,
|
|
406
|
-
prefix: str = "",
|
|
407
|
-
scope: str = "project",
|
|
408
|
-
limit: int = 100,
|
|
409
|
-
) -> list[dict]:
|
|
410
|
-
"""List keys in a namespace, filtered by prefix.
|
|
659
|
+
def _print_goal_migration_dry_run(db_path: Path) -> int:
|
|
660
|
+
db_path = db_path.resolve()
|
|
411
661
|
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
662
|
+
# Snapshot all labels before opening SQLite: opening in plain read-only mode
|
|
663
|
+
# can interact with existing WAL files, so its own effects must never alter
|
|
664
|
+
# the sidecar or size report.
|
|
665
|
+
try:
|
|
666
|
+
db_stat, wal_stat, shm_stat = _goal_dry_run_file_metadata(db_path)
|
|
667
|
+
except OSError as exc:
|
|
668
|
+
print(f"Database: {db_path}")
|
|
669
|
+
print("Exists: unknown")
|
|
670
|
+
print("Size: unknown")
|
|
671
|
+
print("Sidecars: unknown")
|
|
672
|
+
print("Goal tables exist: unknown")
|
|
673
|
+
print(
|
|
674
|
+
f"Dry-run state is unknown ({exc}); stop and investigate before "
|
|
675
|
+
"any migration.",
|
|
676
|
+
file=sys.stderr,
|
|
677
|
+
)
|
|
678
|
+
return 2
|
|
417
679
|
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
680
|
+
exists = db_stat is not None
|
|
681
|
+
has_wal = wal_stat is not None
|
|
682
|
+
has_shm = shm_stat is not None
|
|
683
|
+
size = (db_stat.st_size if db_stat is not None else 0) + (
|
|
684
|
+
wal_stat.st_size if wal_stat is not None else 0
|
|
685
|
+
)
|
|
686
|
+
size_description = " bytes (database + WAL)" if has_wal else " bytes"
|
|
687
|
+
print(f"Database: {db_path}")
|
|
688
|
+
print(f"Exists: {'yes' if exists else 'no'}")
|
|
689
|
+
print(f"Size: {size}{size_description}")
|
|
690
|
+
sidecar_description = (
|
|
691
|
+
f"WAL={'yes' if has_wal else 'no'}, SHM={'yes' if has_shm else 'no'}"
|
|
692
|
+
)
|
|
693
|
+
print(f"Sidecars: {sidecar_description}")
|
|
694
|
+
|
|
695
|
+
goal_tables = {"pantheon_goal_schema_migrations", "pantheon_goals"}
|
|
696
|
+
table_result = "no"
|
|
697
|
+
if exists:
|
|
698
|
+
connection: sqlite3.Connection | None = None
|
|
699
|
+
try:
|
|
700
|
+
uri = f"{db_path.as_uri()}?mode=ro"
|
|
701
|
+
if not has_wal and not has_shm:
|
|
702
|
+
uri += "&immutable=1"
|
|
703
|
+
connection = sqlite3.connect(uri, uri=True)
|
|
704
|
+
present = goal_tables & {
|
|
705
|
+
str(row[0])
|
|
706
|
+
for row in connection.execute(
|
|
707
|
+
"SELECT name FROM sqlite_master WHERE type = 'table'"
|
|
708
|
+
)
|
|
709
|
+
}
|
|
710
|
+
table_result = "yes" if present else "no"
|
|
711
|
+
if present:
|
|
712
|
+
table_result += f" ({', '.join(sorted(present))})"
|
|
713
|
+
except sqlite3.Error as exc:
|
|
714
|
+
table_result = "unknown"
|
|
715
|
+
print(
|
|
716
|
+
f"Dry-run state is unknown ({exc}); stop and investigate before "
|
|
717
|
+
"any migration.",
|
|
718
|
+
file=sys.stderr,
|
|
719
|
+
)
|
|
720
|
+
finally:
|
|
721
|
+
if connection is not None:
|
|
722
|
+
connection.close()
|
|
723
|
+
print(f"Goal tables exist: {table_result}")
|
|
724
|
+
print(
|
|
725
|
+
"Warning: stop the Persistence server for an authoritative check and "
|
|
726
|
+
"keep it stopped for the whole migration."
|
|
727
|
+
)
|
|
728
|
+
return 2 if table_result == "unknown" else 0
|
|
729
|
+
|
|
730
|
+
|
|
731
|
+
def _warn_if_symlinked_launcher() -> None:
|
|
732
|
+
lexical_path = Path(__file__).absolute()
|
|
733
|
+
resolved_path = Path(__file__).resolve()
|
|
734
|
+
if lexical_path != resolved_path:
|
|
735
|
+
print(
|
|
736
|
+
"Warning: this is a symlinked launcher; re-run from the installed script "
|
|
737
|
+
f"at {resolved_path}.",
|
|
738
|
+
file=sys.stderr,
|
|
739
|
+
)
|
|
740
|
+
|
|
741
|
+
|
|
742
|
+
def _print_goal_migration_failure(
|
|
743
|
+
error: GoalStoreError | OSError | sqlite3.Error,
|
|
744
|
+
) -> None:
|
|
745
|
+
print(f"Goal schema migration failed: {error}", file=sys.stderr)
|
|
746
|
+
if isinstance(error, GoalBackupRetainedError):
|
|
747
|
+
print(
|
|
748
|
+
f"Verified backup retained at: {error.backup_path}",
|
|
749
|
+
file=sys.stderr,
|
|
750
|
+
)
|
|
751
|
+
|
|
752
|
+
|
|
753
|
+
def _reserve_goal_backup_path(db_path: Path) -> Path:
|
|
754
|
+
timestamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S.%fZ")
|
|
755
|
+
backup_path = db_path.with_name(f"{db_path.name}.goal-backup-{timestamp}.sqlite3")
|
|
756
|
+
try:
|
|
757
|
+
descriptor = os.open(
|
|
758
|
+
backup_path,
|
|
759
|
+
os.O_CREAT | os.O_EXCL | os.O_WRONLY,
|
|
760
|
+
0o600,
|
|
761
|
+
)
|
|
762
|
+
except OSError as exc:
|
|
763
|
+
raise GoalStorageError(
|
|
764
|
+
f"could not reserve unique goal schema backup {backup_path}"
|
|
765
|
+
) from exc
|
|
766
|
+
os.close(descriptor)
|
|
767
|
+
return backup_path
|
|
768
|
+
|
|
769
|
+
|
|
770
|
+
def _sqlite_object_names(conn: sqlite3.Connection) -> set[str]:
|
|
771
|
+
return {str(row[0]) for row in conn.execute("SELECT name FROM sqlite_master")}
|
|
772
|
+
|
|
773
|
+
|
|
774
|
+
def _sqlite_table_row_counts(conn: sqlite3.Connection) -> dict[str, int]:
|
|
775
|
+
tables = conn.execute(
|
|
776
|
+
"SELECT name FROM sqlite_master WHERE type = 'table'"
|
|
429
777
|
).fetchall()
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
}
|
|
437
|
-
for r in rows
|
|
438
|
-
]
|
|
778
|
+
row_counts: dict[str, int] = {}
|
|
779
|
+
for (table_name,) in tables:
|
|
780
|
+
quoted_name = '"' + str(table_name).replace('"', '""') + '"'
|
|
781
|
+
row = conn.execute(f"SELECT COUNT(*) FROM {quoted_name}").fetchone()
|
|
782
|
+
row_counts[str(table_name)] = int(row[0])
|
|
783
|
+
return row_counts
|
|
439
784
|
|
|
440
785
|
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
786
|
+
def _verify_goal_backup(
|
|
787
|
+
source: sqlite3.Connection, backup_path: Path, expected_version: int
|
|
788
|
+
) -> None:
|
|
789
|
+
uri = f"{backup_path.as_uri()}?mode=ro&immutable=1"
|
|
790
|
+
backup: sqlite3.Connection | None = None
|
|
791
|
+
try:
|
|
792
|
+
backup = sqlite3.connect(uri, uri=True)
|
|
793
|
+
check = backup.execute("PRAGMA quick_check").fetchone()
|
|
794
|
+
if check is None or check[0] != "ok":
|
|
795
|
+
raise GoalStorageError("goal schema backup failed SQLite integrity check")
|
|
796
|
+
source_page_count = int(source.execute("PRAGMA page_count").fetchone()[0])
|
|
797
|
+
backup_page_count = int(backup.execute("PRAGMA page_count").fetchone()[0])
|
|
798
|
+
if source_page_count < 1 or backup_page_count != source_page_count:
|
|
799
|
+
raise GoalStorageError(
|
|
800
|
+
"goal schema backup page-count verification failed: "
|
|
801
|
+
f"expected {source_page_count}, found {backup_page_count}"
|
|
802
|
+
)
|
|
803
|
+
source_objects = _sqlite_object_names(source)
|
|
804
|
+
backup_objects = _sqlite_object_names(backup)
|
|
805
|
+
if source_objects != backup_objects:
|
|
806
|
+
raise GoalStorageError(
|
|
807
|
+
"goal schema backup SQLite object-name verification failed"
|
|
808
|
+
)
|
|
809
|
+
if "kv_store" not in source_objects or "kv_store" not in backup_objects:
|
|
810
|
+
raise GoalSchemaNotInitializedError(
|
|
811
|
+
"target is not a Pantheon Persistence database: kv_store is missing; "
|
|
812
|
+
"ask the user to start the server once first"
|
|
813
|
+
)
|
|
814
|
+
if _sqlite_table_row_counts(source) != _sqlite_table_row_counts(backup):
|
|
815
|
+
raise GoalStorageError(
|
|
816
|
+
"goal schema backup row-count verification failed for kv_store "
|
|
817
|
+
"or another sentinel table"
|
|
818
|
+
)
|
|
819
|
+
actual_version = _raw_goal_schema_version(backup)
|
|
820
|
+
if actual_version != expected_version:
|
|
821
|
+
raise GoalStorageError(
|
|
822
|
+
"goal schema backup version verification failed: "
|
|
823
|
+
f"expected {expected_version}, found {actual_version}"
|
|
824
|
+
)
|
|
825
|
+
except sqlite3.Error as exc:
|
|
826
|
+
raise GoalStorageError("could not verify goal schema backup") from exc
|
|
827
|
+
finally:
|
|
828
|
+
if backup is not None:
|
|
829
|
+
backup.close()
|
|
830
|
+
|
|
831
|
+
|
|
832
|
+
def _copy_goal_backup(source: sqlite3.Connection, backup_path: Path) -> None:
|
|
833
|
+
"""Write and durably flush the full SQLite backup before verification."""
|
|
834
|
+
destination = sqlite3.connect(str(backup_path))
|
|
835
|
+
try:
|
|
836
|
+
source.backup(destination)
|
|
837
|
+
finally:
|
|
838
|
+
destination.close()
|
|
839
|
+
os.chmod(backup_path, 0o600)
|
|
840
|
+
with backup_path.open("rb") as backup_file:
|
|
841
|
+
os.fsync(backup_file.fileno())
|
|
842
|
+
directory_fd = os.open(
|
|
843
|
+
backup_path.parent,
|
|
844
|
+
os.O_RDONLY | getattr(os, "O_DIRECTORY", 0),
|
|
845
|
+
)
|
|
846
|
+
try:
|
|
847
|
+
os.fsync(directory_fd)
|
|
848
|
+
finally:
|
|
849
|
+
os.close(directory_fd)
|
|
850
|
+
|
|
851
|
+
|
|
852
|
+
def _remove_goal_backup_sidecars(backup_path: Path) -> None:
|
|
853
|
+
for suffix in ("-wal", "-shm", "-journal"):
|
|
854
|
+
with suppress(OSError):
|
|
855
|
+
backup_path.with_name(backup_path.name + suffix).unlink(missing_ok=True)
|
|
856
|
+
|
|
857
|
+
|
|
858
|
+
def _cleanup_goal_backup(backup_path: Path) -> None:
|
|
859
|
+
_remove_goal_backup_sidecars(backup_path)
|
|
860
|
+
with suppress(OSError):
|
|
861
|
+
backup_path.unlink(missing_ok=True)
|
|
862
|
+
|
|
863
|
+
|
|
864
|
+
def migrate_goal_schema_with_backup(
|
|
865
|
+
project_db_path: str | Path,
|
|
866
|
+
*,
|
|
867
|
+
explicit_project_db: bool = True,
|
|
868
|
+
) -> tuple[Path, Path | None, int, bool]:
|
|
869
|
+
"""Back up an existing Persistence DB, then migrate its goal schema."""
|
|
870
|
+
db_path = Path(project_db_path).expanduser().resolve()
|
|
871
|
+
if not db_path.is_file():
|
|
872
|
+
raise GoalSchemaNotInitializedError(
|
|
873
|
+
f"Persistence database does not exist at {db_path}; "
|
|
874
|
+
"ask the user to start the server once first"
|
|
875
|
+
)
|
|
876
|
+
try:
|
|
877
|
+
source = sqlite3.connect(f"{db_path.as_uri()}?mode=rw", uri=True, timeout=5)
|
|
878
|
+
except sqlite3.Error as exc:
|
|
879
|
+
raise GoalStorageError("could not open Persistence database") from exc
|
|
880
|
+
|
|
881
|
+
backup_path: Path | None = None
|
|
882
|
+
try:
|
|
883
|
+
has_kv_store = source.execute(
|
|
884
|
+
"SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'kv_store'"
|
|
885
|
+
).fetchone()
|
|
886
|
+
if has_kv_store is None:
|
|
887
|
+
raise GoalSchemaNotInitializedError(
|
|
888
|
+
"target is not a Pantheon Persistence database: kv_store is missing; "
|
|
889
|
+
"ask the user to start the server once first"
|
|
890
|
+
)
|
|
891
|
+
_assert_project_goal_connection(
|
|
892
|
+
source,
|
|
893
|
+
db_path,
|
|
894
|
+
explicit_project_db=explicit_project_db,
|
|
895
|
+
)
|
|
896
|
+
current = _inspect_goal_schema_version(source)
|
|
897
|
+
original_version = _raw_goal_schema_version(source)
|
|
898
|
+
if current == GOAL_SCHEMA_VERSION:
|
|
899
|
+
return db_path, None, original_version, True
|
|
900
|
+
|
|
901
|
+
backup_path = _reserve_goal_backup_path(db_path)
|
|
902
|
+
try:
|
|
903
|
+
_copy_goal_backup(source, backup_path)
|
|
904
|
+
_remove_goal_backup_sidecars(backup_path)
|
|
905
|
+
_verify_goal_backup(source, backup_path, original_version)
|
|
906
|
+
except (GoalStoreError, OSError, sqlite3.Error):
|
|
907
|
+
_cleanup_goal_backup(backup_path)
|
|
908
|
+
raise
|
|
909
|
+
|
|
910
|
+
try:
|
|
911
|
+
upgrade_goal_schema(
|
|
912
|
+
source,
|
|
913
|
+
db_path,
|
|
914
|
+
explicit_project_db=explicit_project_db,
|
|
915
|
+
)
|
|
916
|
+
version = _raw_goal_schema_version(source)
|
|
917
|
+
except Exception as exc:
|
|
918
|
+
raise GoalBackupRetainedError(backup_path, exc) from exc
|
|
919
|
+
return db_path, backup_path, version, False
|
|
920
|
+
finally:
|
|
921
|
+
source.close()
|
|
922
|
+
|
|
923
|
+
|
|
924
|
+
_GOAL_COLUMNS = (
|
|
925
|
+
"goal_id, session_id, title, description, status, created_at, updated_at, version"
|
|
445
926
|
)
|
|
446
|
-
async def kv_search(
|
|
447
|
-
query: str,
|
|
448
|
-
namespace: str | None = None,
|
|
449
|
-
scope: str = "project",
|
|
450
|
-
limit: int = 20,
|
|
451
|
-
) -> list[dict]:
|
|
452
|
-
"""Full-text search across keys and values.
|
|
453
927
|
|
|
454
|
-
Args:
|
|
455
|
-
query: Free-text search terms (max 10 terms quoted).
|
|
456
|
-
namespace: Optional namespace filter.
|
|
457
|
-
scope: 'project' (default) or 'global'.
|
|
458
|
-
limit: Maximum number of results (default 20).
|
|
459
928
|
|
|
460
|
-
|
|
461
|
-
|
|
929
|
+
def _goal_from_row(row: sqlite3.Row | tuple[object, ...]) -> GoalRecord:
|
|
930
|
+
return GoalRecord(
|
|
931
|
+
goal_id=str(row[0]),
|
|
932
|
+
session_id=str(row[1]),
|
|
933
|
+
title=str(row[2]),
|
|
934
|
+
description=row[3] if isinstance(row[3], str) else None,
|
|
935
|
+
status=row[4], # type: ignore[arg-type]
|
|
936
|
+
created_at=str(row[5]),
|
|
937
|
+
updated_at=str(row[6]),
|
|
938
|
+
version=int(row[7]),
|
|
939
|
+
)
|
|
940
|
+
|
|
941
|
+
|
|
942
|
+
def _goal_by_id(
|
|
943
|
+
conn: sqlite3.Connection, session_id: str, goal_id: str
|
|
944
|
+
) -> GoalRecord | None:
|
|
945
|
+
row = conn.execute(
|
|
946
|
+
f"SELECT {_GOAL_COLUMNS} FROM pantheon_goals "
|
|
947
|
+
"WHERE session_id = ? AND goal_id = ?",
|
|
948
|
+
(session_id, goal_id),
|
|
949
|
+
).fetchone()
|
|
950
|
+
return _goal_from_row(row) if row is not None else None
|
|
951
|
+
|
|
952
|
+
|
|
953
|
+
def _goal_database_error(exc: sqlite3.Error) -> GoalStoreError:
|
|
954
|
+
if "no such table: pantheon_goals" in str(exc):
|
|
955
|
+
return GoalSchemaNotInitializedError(
|
|
956
|
+
"goal schema is not initialized. Ask the user to run "
|
|
957
|
+
f"`{GOAL_SCHEMA_MIGRATION_COMMAND}`; goal schema migration is a "
|
|
958
|
+
"human-approved operation. "
|
|
959
|
+
f"{GOAL_SCHEMA_MIGRATION_COMMAND_GUIDANCE}"
|
|
960
|
+
)
|
|
961
|
+
return GoalStorageError("goal database operation failed")
|
|
962
|
+
|
|
963
|
+
|
|
964
|
+
def create_goal(
|
|
965
|
+
*,
|
|
966
|
+
session_id: str,
|
|
967
|
+
title: str,
|
|
968
|
+
description: str | None = None,
|
|
969
|
+
) -> GoalRecord:
|
|
970
|
+
"""Create one active goal; session identity must come from trusted host context.
|
|
971
|
+
|
|
972
|
+
The session ID is a correlation/scope key, not authentication. Callers must
|
|
973
|
+
supply it internally from OpenCode ``Context`` metadata; never accept it as
|
|
974
|
+
a model-controlled tool argument.
|
|
462
975
|
"""
|
|
463
|
-
conn =
|
|
976
|
+
conn = _project_goal_connection()
|
|
977
|
+
session_id = _validate_goal_session_id(session_id)
|
|
978
|
+
title = _validate_goal_text(title, "title", GOAL_TITLE_MAX_LENGTH)
|
|
979
|
+
if description is not None:
|
|
980
|
+
description = _validate_goal_text(
|
|
981
|
+
description,
|
|
982
|
+
"description",
|
|
983
|
+
GOAL_DESCRIPTION_MAX_LENGTH,
|
|
984
|
+
allow_newlines=True,
|
|
985
|
+
)
|
|
986
|
+
try:
|
|
987
|
+
with _goal_transaction(conn):
|
|
988
|
+
_require_goal_schema(conn)
|
|
989
|
+
existing = conn.execute(
|
|
990
|
+
f"SELECT {_GOAL_COLUMNS} FROM pantheon_goals "
|
|
991
|
+
"WHERE session_id = ? AND status = 'active'",
|
|
992
|
+
(session_id,),
|
|
993
|
+
).fetchone()
|
|
994
|
+
if existing is not None:
|
|
995
|
+
raise ActiveGoalExistsError(
|
|
996
|
+
"active goal already exists for this session"
|
|
997
|
+
)
|
|
998
|
+
now = _goal_timestamp()
|
|
999
|
+
goal_id = uuid4().hex
|
|
1000
|
+
conn.execute(
|
|
1001
|
+
"INSERT INTO pantheon_goals(" + _GOAL_COLUMNS + ") "
|
|
1002
|
+
"VALUES (?, ?, ?, ?, 'active', ?, ?, 1)",
|
|
1003
|
+
(goal_id, session_id, title, description, now, now),
|
|
1004
|
+
)
|
|
1005
|
+
created = _goal_by_id(conn, session_id, goal_id)
|
|
1006
|
+
assert created is not None
|
|
1007
|
+
return created
|
|
1008
|
+
except sqlite3.IntegrityError as exc:
|
|
1009
|
+
try:
|
|
1010
|
+
with _goal_write_lock:
|
|
1011
|
+
_require_goal_schema(conn)
|
|
1012
|
+
existing = conn.execute(
|
|
1013
|
+
"SELECT 1 FROM pantheon_goals "
|
|
1014
|
+
"WHERE session_id = ? AND status = 'active'",
|
|
1015
|
+
(session_id,),
|
|
1016
|
+
).fetchone()
|
|
1017
|
+
if existing is not None:
|
|
1018
|
+
raise ActiveGoalExistsError(
|
|
1019
|
+
"active goal already exists for this session"
|
|
1020
|
+
) from exc
|
|
1021
|
+
except GoalStoreError:
|
|
1022
|
+
raise
|
|
1023
|
+
except sqlite3.Error as inspect_exc:
|
|
1024
|
+
raise _goal_database_error(inspect_exc) from exc
|
|
1025
|
+
raise GoalStorageError("goal insert violated a database constraint") from exc
|
|
1026
|
+
except sqlite3.Error as exc:
|
|
1027
|
+
raise _goal_database_error(exc) from exc
|
|
464
1028
|
|
|
465
|
-
# Sanitize: extract up to 10 word tokens, wrap each in quotes
|
|
466
|
-
terms = re.findall(r"\w+", query)[:10]
|
|
467
|
-
terms = [re.escape(t) for t in terms]
|
|
468
|
-
if not terms:
|
|
469
|
-
return []
|
|
470
|
-
fts_query = " OR ".join(f'"{t}"' for t in terms)
|
|
471
|
-
|
|
472
|
-
sql: str = (
|
|
473
|
-
"SELECT kv_store.namespace, kv_store.key, kv_store.value, kv_store.created_at, "
|
|
474
|
-
"BM25(kv_store_fts) AS score "
|
|
475
|
-
"FROM kv_store_fts "
|
|
476
|
-
"JOIN kv_store ON kv_store_fts.rowid = kv_store.id "
|
|
477
|
-
"WHERE kv_store_fts MATCH ? "
|
|
478
|
-
"AND kv_store.deleted_at IS NULL "
|
|
479
|
-
"AND (kv_store.expires_at IS NULL OR "
|
|
480
|
-
"julianday(kv_store.expires_at) > julianday('now'))"
|
|
481
|
-
)
|
|
482
|
-
params: list[str | int] = [fts_query]
|
|
483
|
-
|
|
484
|
-
if namespace is not None:
|
|
485
|
-
sql += " AND kv_store.namespace = ?"
|
|
486
|
-
params.append(namespace)
|
|
487
|
-
|
|
488
|
-
sql += " ORDER BY score LIMIT ?"
|
|
489
|
-
params.append(limit)
|
|
490
|
-
|
|
491
|
-
rows = conn.execute(sql, params).fetchall()
|
|
492
|
-
return [
|
|
493
|
-
{
|
|
494
|
-
"namespace": r[0],
|
|
495
|
-
"key": r[1],
|
|
496
|
-
"value": r[2],
|
|
497
|
-
"created_at": r[3],
|
|
498
|
-
"score": round(float(r[4]), 4),
|
|
499
|
-
}
|
|
500
|
-
for r in rows
|
|
501
|
-
]
|
|
502
1029
|
|
|
1030
|
+
def get_goal(*, session_id: str, goal_id: str | None = None) -> GoalRecord | None:
|
|
1031
|
+
"""Get a specific goal, or its active/latest history entry.
|
|
503
1032
|
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
1033
|
+
SQLite rowid provides an insertion-order tie-break when creation timestamps
|
|
1034
|
+
are equal.
|
|
1035
|
+
"""
|
|
1036
|
+
conn = _project_goal_connection()
|
|
1037
|
+
session_id = _validate_goal_session_id(session_id)
|
|
1038
|
+
if goal_id is not None:
|
|
1039
|
+
goal_id = _validate_goal_id(goal_id)
|
|
1040
|
+
try:
|
|
1041
|
+
with _goal_write_lock:
|
|
1042
|
+
_require_goal_schema(conn)
|
|
1043
|
+
if goal_id is not None:
|
|
1044
|
+
return _goal_by_id(conn, session_id, goal_id)
|
|
1045
|
+
row = conn.execute(
|
|
1046
|
+
f"SELECT {_GOAL_COLUMNS} FROM pantheon_goals "
|
|
1047
|
+
"WHERE session_id = ? AND status = 'active' LIMIT 1",
|
|
1048
|
+
(session_id,),
|
|
1049
|
+
).fetchone()
|
|
1050
|
+
if row is None:
|
|
1051
|
+
row = conn.execute(
|
|
1052
|
+
f"SELECT {_GOAL_COLUMNS} FROM pantheon_goals "
|
|
1053
|
+
"WHERE session_id = ? ORDER BY created_at DESC, rowid DESC "
|
|
1054
|
+
"LIMIT 1",
|
|
1055
|
+
(session_id,),
|
|
1056
|
+
).fetchone()
|
|
1057
|
+
return _goal_from_row(row) if row is not None else None
|
|
1058
|
+
except sqlite3.Error as exc:
|
|
1059
|
+
raise _goal_database_error(exc) from exc
|
|
1060
|
+
|
|
1061
|
+
|
|
1062
|
+
def update_goal(
|
|
1063
|
+
*,
|
|
1064
|
+
session_id: str,
|
|
1065
|
+
goal_id: str,
|
|
1066
|
+
expected_version: int,
|
|
1067
|
+
title: str | None | _GoalUnset = _GOAL_UNSET,
|
|
1068
|
+
description: str | None | _GoalUnset = _GOAL_UNSET,
|
|
1069
|
+
) -> GoalRecord:
|
|
1070
|
+
"""CAS-update user fields only; status and version remain server-owned."""
|
|
1071
|
+
conn = _project_goal_connection()
|
|
1072
|
+
session_id = _validate_goal_session_id(session_id)
|
|
1073
|
+
goal_id = _validate_goal_id(goal_id)
|
|
1074
|
+
expected_version = _validate_goal_version(expected_version)
|
|
1075
|
+
if title is _GOAL_UNSET and description is _GOAL_UNSET:
|
|
1076
|
+
raise GoalValidationError("update must include title and/or description")
|
|
1077
|
+
if title is not _GOAL_UNSET:
|
|
1078
|
+
title = _validate_goal_text(title, "title", GOAL_TITLE_MAX_LENGTH)
|
|
1079
|
+
if description is not _GOAL_UNSET and description is not None:
|
|
1080
|
+
description = _validate_goal_text(
|
|
1081
|
+
description,
|
|
1082
|
+
"description",
|
|
1083
|
+
GOAL_DESCRIPTION_MAX_LENGTH,
|
|
1084
|
+
allow_newlines=True,
|
|
1085
|
+
)
|
|
1086
|
+
try:
|
|
1087
|
+
with _goal_transaction(conn):
|
|
1088
|
+
_require_goal_schema(conn)
|
|
1089
|
+
current = _goal_by_id(conn, session_id, goal_id)
|
|
1090
|
+
if current is None:
|
|
1091
|
+
raise GoalNotFoundError("goal not found for this session")
|
|
1092
|
+
if current.version != expected_version:
|
|
1093
|
+
raise GoalVersionConflictError(
|
|
1094
|
+
f"goal version conflict: expected {expected_version}, "
|
|
1095
|
+
f"current version is {current.version}"
|
|
1096
|
+
)
|
|
1097
|
+
new_title = current.title if title is _GOAL_UNSET else title
|
|
1098
|
+
new_description = (
|
|
1099
|
+
current.description if description is _GOAL_UNSET else description
|
|
1100
|
+
)
|
|
1101
|
+
conn.execute(
|
|
1102
|
+
"UPDATE pantheon_goals SET title = ?, description = ?, "
|
|
1103
|
+
"updated_at = ?, version = version + 1 "
|
|
1104
|
+
"WHERE goal_id = ? AND session_id = ? AND version = ?",
|
|
1105
|
+
(
|
|
1106
|
+
new_title,
|
|
1107
|
+
new_description,
|
|
1108
|
+
_goal_timestamp(),
|
|
1109
|
+
goal_id,
|
|
1110
|
+
session_id,
|
|
1111
|
+
expected_version,
|
|
1112
|
+
),
|
|
1113
|
+
)
|
|
1114
|
+
updated = _goal_by_id(conn, session_id, goal_id)
|
|
1115
|
+
assert updated is not None
|
|
1116
|
+
if updated.version != expected_version + 1:
|
|
1117
|
+
raise GoalVersionConflictError(
|
|
1118
|
+
f"goal version conflict: expected {expected_version}, "
|
|
1119
|
+
f"current version is {updated.version}"
|
|
1120
|
+
)
|
|
1121
|
+
return updated
|
|
1122
|
+
except sqlite3.Error as exc:
|
|
1123
|
+
raise _goal_database_error(exc) from exc
|
|
1124
|
+
|
|
1125
|
+
|
|
1126
|
+
def complete_goal(
|
|
1127
|
+
*,
|
|
1128
|
+
session_id: str,
|
|
1129
|
+
goal_id: str,
|
|
1130
|
+
expected_version: int,
|
|
1131
|
+
) -> GoalRecord:
|
|
1132
|
+
"""Mark a session-owned active goal done using CAS; repeated done is idempotent."""
|
|
1133
|
+
conn = _project_goal_connection()
|
|
1134
|
+
session_id = _validate_goal_session_id(session_id)
|
|
1135
|
+
goal_id = _validate_goal_id(goal_id)
|
|
1136
|
+
expected_version = _validate_goal_version(expected_version)
|
|
1137
|
+
try:
|
|
1138
|
+
with _goal_transaction(conn):
|
|
1139
|
+
_require_goal_schema(conn)
|
|
1140
|
+
current = _goal_by_id(conn, session_id, goal_id)
|
|
1141
|
+
if current is None:
|
|
1142
|
+
raise GoalNotFoundError("goal not found for this session")
|
|
1143
|
+
if current.status == "done":
|
|
1144
|
+
return current
|
|
1145
|
+
if current.version != expected_version:
|
|
1146
|
+
raise GoalVersionConflictError(
|
|
1147
|
+
f"goal version conflict: expected {expected_version}, "
|
|
1148
|
+
f"current version is {current.version}"
|
|
1149
|
+
)
|
|
1150
|
+
conn.execute(
|
|
1151
|
+
"UPDATE pantheon_goals SET status = 'done', updated_at = ?, "
|
|
1152
|
+
"version = version + 1 WHERE goal_id = ? AND session_id = ? "
|
|
1153
|
+
"AND status = 'active' AND version = ?",
|
|
1154
|
+
(_goal_timestamp(), goal_id, session_id, expected_version),
|
|
1155
|
+
)
|
|
1156
|
+
completed = _goal_by_id(conn, session_id, goal_id)
|
|
1157
|
+
assert completed is not None
|
|
1158
|
+
if completed.status != "done" or completed.version != expected_version + 1:
|
|
1159
|
+
raise GoalVersionConflictError(
|
|
1160
|
+
f"goal version conflict: expected {expected_version}, "
|
|
1161
|
+
f"current version is {completed.version}"
|
|
1162
|
+
)
|
|
1163
|
+
return completed
|
|
1164
|
+
except sqlite3.Error as exc:
|
|
1165
|
+
raise _goal_database_error(exc) from exc
|
|
1166
|
+
|
|
1167
|
+
|
|
1168
|
+
# ── Resolve scope and init databases ────────────────────────────────────────────
|
|
1169
|
+
|
|
1170
|
+
parser = argparse.ArgumentParser()
|
|
1171
|
+
parser.add_argument("--global-db", default=None)
|
|
1172
|
+
parser.add_argument("--project-db", default=None)
|
|
1173
|
+
parser.add_argument(
|
|
1174
|
+
"--migrate-goals",
|
|
1175
|
+
action="store_true",
|
|
1176
|
+
help="back up and explicitly migrate the Persistence goal schema, then exit",
|
|
508
1177
|
)
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
1178
|
+
parser.add_argument(
|
|
1179
|
+
"--dry-run",
|
|
1180
|
+
action="store_true",
|
|
1181
|
+
help="with --migrate-goals, report the resolved DB without changing it",
|
|
1182
|
+
)
|
|
1183
|
+
args = parser.parse_args()
|
|
514
1184
|
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
dry_run: If True, only report count without purging.
|
|
1185
|
+
if args.dry_run and not args.migrate_goals:
|
|
1186
|
+
parser.error("--dry-run requires --migrate-goals")
|
|
518
1187
|
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
1188
|
+
_project_db_path: Path | None = None
|
|
1189
|
+
_project_db_explicit = args.project_db is not None
|
|
1190
|
+
if args.migrate_goals:
|
|
1191
|
+
_warn_if_symlinked_launcher()
|
|
1192
|
+
try:
|
|
1193
|
+
migration_db_path = _resolve_project_db_path(args.project_db)
|
|
1194
|
+
if args.dry_run:
|
|
1195
|
+
raise SystemExit(_print_goal_migration_dry_run(migration_db_path))
|
|
1196
|
+
db_path, backup_path, version, already_current = (
|
|
1197
|
+
migrate_goal_schema_with_backup(
|
|
1198
|
+
migration_db_path,
|
|
1199
|
+
explicit_project_db=args.project_db is not None,
|
|
1200
|
+
)
|
|
1201
|
+
)
|
|
1202
|
+
except (GoalStoreError, OSError, sqlite3.Error) as exc:
|
|
1203
|
+
_print_goal_migration_failure(exc)
|
|
1204
|
+
raise SystemExit(1) from exc
|
|
1205
|
+
print(f"Database: {db_path}")
|
|
1206
|
+
if backup_path is not None:
|
|
1207
|
+
print(f"Backup: {backup_path}")
|
|
1208
|
+
print(f"Goal schema version: {version}")
|
|
1209
|
+
if already_current:
|
|
1210
|
+
print("Goal schema already current; no schema changes applied.")
|
|
1211
|
+
else:
|
|
1212
|
+
print("Goal schema migration applied.")
|
|
1213
|
+
raise SystemExit(0)
|
|
523
1214
|
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
"AND julianday(expires_at) < julianday('now') "
|
|
529
|
-
"AND deleted_at IS NULL",
|
|
530
|
-
).fetchall()
|
|
531
|
-
expired_keys = [r[0] for r in expired]
|
|
532
|
-
count = len(expired_keys)
|
|
1215
|
+
_global_root = (
|
|
1216
|
+
Path(args.global_db) if args.global_db else pantheon_home() / "persistence"
|
|
1217
|
+
)
|
|
1218
|
+
_global_db = _init_db(_global_root / "global.db")
|
|
533
1219
|
|
|
534
|
-
|
|
535
|
-
|
|
1220
|
+
_project_db_path = _resolve_project_db_path(args.project_db)
|
|
1221
|
+
_project_db_instance = _init_db(_project_db_path)
|
|
1222
|
+
_project_db = _project_db_instance
|
|
536
1223
|
|
|
537
|
-
if count == 0:
|
|
538
|
-
return {"purged": 0, "dry_run": False}
|
|
539
1224
|
|
|
540
|
-
|
|
541
|
-
conn.execute(
|
|
542
|
-
"UPDATE kv_store SET deleted_at = datetime('now') "
|
|
543
|
-
"WHERE expires_at IS NOT NULL "
|
|
544
|
-
"AND julianday(expires_at) < julianday('now') "
|
|
545
|
-
"AND deleted_at IS NULL",
|
|
546
|
-
)
|
|
547
|
-
conn.commit()
|
|
1225
|
+
# ── Tools ───────────────────────────────────────────────────────────────────────
|
|
548
1226
|
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
if db_path:
|
|
552
|
-
_write_deletelog(db_path, count, expired_keys)
|
|
1227
|
+
_OPENCODE_SESSION_META_KEY = "ai.opencode/sessionID"
|
|
1228
|
+
_OPENCODE_SESSION_ID_PATTERN = re.compile(r"ses_[A-Za-z0-9_-]{1,124}\Z")
|
|
553
1229
|
|
|
554
|
-
return {"purged": count, "dry_run": False}
|
|
555
1230
|
|
|
1231
|
+
def _session_id_from_context(context: Context) -> str:
|
|
1232
|
+
"""Read and validate the OpenCode session ID from FastMCP request metadata.
|
|
556
1233
|
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
"""
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
(
|
|
564
|
-
|
|
565
|
-
if
|
|
566
|
-
|
|
1234
|
+
This value is a correlation/scope key, not authentication. The supported
|
|
1235
|
+
boundary is OpenCode-mediated local stdio; clients able to bypass the host
|
|
1236
|
+
can forge metadata and are outside this check's security guarantee.
|
|
1237
|
+
"""
|
|
1238
|
+
request_context = context.request_context
|
|
1239
|
+
if request_context is None:
|
|
1240
|
+
raise ToolError("Goal operations require OpenCode session metadata.")
|
|
1241
|
+
metadata = request_context.meta
|
|
1242
|
+
if not isinstance(metadata, Mapping):
|
|
1243
|
+
raise ToolError("Goal operations require OpenCode session metadata.")
|
|
1244
|
+
session_id = metadata.get(_OPENCODE_SESSION_META_KEY)
|
|
1245
|
+
if (
|
|
1246
|
+
not isinstance(session_id, str)
|
|
1247
|
+
or _OPENCODE_SESSION_ID_PATTERN.fullmatch(session_id) is None
|
|
1248
|
+
):
|
|
1249
|
+
raise ToolError("Goal operations require a valid OpenCode session ID.")
|
|
1250
|
+
return session_id
|
|
567
1251
|
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
1252
|
+
|
|
1253
|
+
def _public_goal(record: GoalRecord | None) -> dict[str, object] | None:
|
|
1254
|
+
"""Expose only public goal fields; omit session scope and storage details."""
|
|
1255
|
+
if record is None:
|
|
1256
|
+
return None
|
|
1257
|
+
return {
|
|
1258
|
+
"goal_id": record.goal_id,
|
|
1259
|
+
"title": record.title,
|
|
1260
|
+
"description": record.description,
|
|
1261
|
+
"status": record.status,
|
|
1262
|
+
"created_at": record.created_at,
|
|
1263
|
+
"updated_at": record.updated_at,
|
|
1264
|
+
"version": record.version,
|
|
1265
|
+
}
|
|
1266
|
+
|
|
1267
|
+
|
|
1268
|
+
def _goal_tool_error(error: GoalStoreError) -> ToolError:
|
|
1269
|
+
"""Translate repository errors to safe, actionable MCP tool errors."""
|
|
1270
|
+
if isinstance(error, ActiveGoalExistsError):
|
|
1271
|
+
message = "This session already has an active goal. Use goal_get or update it."
|
|
1272
|
+
elif isinstance(error, GoalNotFoundError):
|
|
1273
|
+
message = "No goal with that ID exists in this session."
|
|
1274
|
+
elif isinstance(error, GoalVersionConflictError):
|
|
1275
|
+
message = (
|
|
1276
|
+
"The goal changed since the supplied version. Call goal_get and retry "
|
|
1277
|
+
"with its current version."
|
|
1278
|
+
)
|
|
1279
|
+
elif isinstance(error, GoalValidationError):
|
|
1280
|
+
message = f"Invalid goal request: {error}"
|
|
1281
|
+
elif isinstance(error, GoalSchemaNotInitializedError | GoalSchemaVersionError):
|
|
1282
|
+
message = str(error)
|
|
1283
|
+
else:
|
|
1284
|
+
message = "Goal storage is unavailable; no database details were exposed."
|
|
1285
|
+
return ToolError(message)
|
|
575
1286
|
|
|
576
1287
|
|
|
577
1288
|
@mcp.tool(
|
|
578
|
-
name="
|
|
1289
|
+
name="goal_create",
|
|
579
1290
|
description=(
|
|
580
|
-
"
|
|
581
|
-
"
|
|
1291
|
+
"Create one active manual goal for the current OpenCode session in this "
|
|
1292
|
+
"Persistence deployment database. Session identity comes from "
|
|
1293
|
+
"host request metadata, not tool arguments. Completed goals remain in "
|
|
1294
|
+
"history and allow a new goal. This does not trigger continuation."
|
|
582
1295
|
),
|
|
583
1296
|
)
|
|
584
|
-
async def
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
1297
|
+
async def goal_create(
|
|
1298
|
+
title: Annotated[str, Field(min_length=1, max_length=GOAL_TITLE_MAX_LENGTH)],
|
|
1299
|
+
context: Context,
|
|
1300
|
+
description: Annotated[
|
|
1301
|
+
str | None, Field(max_length=GOAL_DESCRIPTION_MAX_LENGTH)
|
|
1302
|
+
] = None,
|
|
1303
|
+
) -> dict[str, object]:
|
|
1304
|
+
"""Create the current session's single active manual goal."""
|
|
1305
|
+
try:
|
|
1306
|
+
record = create_goal(
|
|
1307
|
+
session_id=_session_id_from_context(context),
|
|
1308
|
+
title=title,
|
|
1309
|
+
description=description,
|
|
1310
|
+
)
|
|
1311
|
+
except GoalStoreError as exc:
|
|
1312
|
+
raise _goal_tool_error(exc) from None
|
|
1313
|
+
return {"goal": _public_goal(record)}
|
|
590
1314
|
|
|
591
|
-
Args:
|
|
592
|
-
namespace: Namespace to clear.
|
|
593
|
-
scope: 'project' (default) or 'global'.
|
|
594
|
-
older_than_days: If set, only delete entries older than this many days.
|
|
595
1315
|
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
1316
|
+
@mcp.tool(
|
|
1317
|
+
name="goal_get",
|
|
1318
|
+
description=(
|
|
1319
|
+
"Read a goal owned by the current OpenCode session. Omit goal_id to "
|
|
1320
|
+
"get its active goal, or its latest completed goal when none is active. "
|
|
1321
|
+
"The returned version is required for goal_update and goal_done."
|
|
1322
|
+
),
|
|
1323
|
+
)
|
|
1324
|
+
async def goal_get(
|
|
1325
|
+
context: Context,
|
|
1326
|
+
goal_id: Annotated[str | None, Field(max_length=GOAL_ID_MAX_LENGTH)] = None,
|
|
1327
|
+
) -> dict[str, object | None]:
|
|
1328
|
+
"""Read the current session's active goal or retained history entry."""
|
|
1329
|
+
try:
|
|
1330
|
+
record = get_goal(session_id=_session_id_from_context(context), goal_id=goal_id)
|
|
1331
|
+
except GoalStoreError as exc:
|
|
1332
|
+
raise _goal_tool_error(exc) from None
|
|
1333
|
+
return {"goal": _public_goal(record)}
|
|
1334
|
+
|
|
600
1335
|
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
1336
|
+
@mcp.tool(
|
|
1337
|
+
name="goal_update",
|
|
1338
|
+
description=(
|
|
1339
|
+
"Edit title and/or description of a goal owned by the current session. "
|
|
1340
|
+
"Supply the version returned by goal_get; stale writes conflict. Status "
|
|
1341
|
+
"and timestamps are server-owned, and a completed goal cannot be reopened. "
|
|
1342
|
+
"Set clear_description=true to remove its optional description."
|
|
1343
|
+
),
|
|
1344
|
+
)
|
|
1345
|
+
async def goal_update(
|
|
1346
|
+
context: Context,
|
|
1347
|
+
goal_id: Annotated[str, Field(min_length=1, max_length=GOAL_ID_MAX_LENGTH)],
|
|
1348
|
+
expected_version: Annotated[int, Field(strict=True, ge=1, le=GOAL_VERSION_MAX)],
|
|
1349
|
+
title: Annotated[
|
|
1350
|
+
str | None, Field(min_length=1, max_length=GOAL_TITLE_MAX_LENGTH)
|
|
1351
|
+
] = None,
|
|
1352
|
+
description: Annotated[
|
|
1353
|
+
str | None, Field(max_length=GOAL_DESCRIPTION_MAX_LENGTH)
|
|
1354
|
+
] = None,
|
|
1355
|
+
clear_description: bool = False,
|
|
1356
|
+
) -> dict[str, object]:
|
|
1357
|
+
"""Update only user-editable fields using the returned optimistic version."""
|
|
1358
|
+
if clear_description and description is not None:
|
|
1359
|
+
raise ToolError("Provide description or clear_description, not both.")
|
|
1360
|
+
changes: dict[str, object] = {}
|
|
1361
|
+
if title is not None:
|
|
1362
|
+
changes["title"] = title
|
|
1363
|
+
if description is not None:
|
|
1364
|
+
changes["description"] = description
|
|
1365
|
+
elif clear_description:
|
|
1366
|
+
changes["description"] = None
|
|
1367
|
+
if not changes:
|
|
1368
|
+
raise ToolError("Provide a title, description, or clear_description change.")
|
|
1369
|
+
try:
|
|
1370
|
+
record = update_goal(
|
|
1371
|
+
session_id=_session_id_from_context(context),
|
|
1372
|
+
goal_id=goal_id,
|
|
1373
|
+
expected_version=expected_version,
|
|
1374
|
+
**changes,
|
|
611
1375
|
)
|
|
612
|
-
|
|
1376
|
+
except GoalStoreError as exc:
|
|
1377
|
+
raise _goal_tool_error(exc) from None
|
|
1378
|
+
return {"goal": _public_goal(record)}
|
|
613
1379
|
|
|
614
|
-
|
|
1380
|
+
|
|
1381
|
+
@mcp.tool(
|
|
1382
|
+
name="goal_done",
|
|
1383
|
+
description=(
|
|
1384
|
+
"Mark a goal owned by the current session completed using its current "
|
|
1385
|
+
"version. Repeating done is idempotent. Completed history is retained, "
|
|
1386
|
+
"and a new active goal may then be created. This does not trigger continuation."
|
|
1387
|
+
),
|
|
1388
|
+
)
|
|
1389
|
+
async def goal_done(
|
|
1390
|
+
context: Context,
|
|
1391
|
+
goal_id: Annotated[str, Field(min_length=1, max_length=GOAL_ID_MAX_LENGTH)],
|
|
1392
|
+
expected_version: Annotated[int, Field(strict=True, ge=1, le=GOAL_VERSION_MAX)],
|
|
1393
|
+
) -> dict[str, object]:
|
|
1394
|
+
"""Complete a current-session goal without changing its user fields."""
|
|
1395
|
+
try:
|
|
1396
|
+
record = complete_goal(
|
|
1397
|
+
session_id=_session_id_from_context(context),
|
|
1398
|
+
goal_id=goal_id,
|
|
1399
|
+
expected_version=expected_version,
|
|
1400
|
+
)
|
|
1401
|
+
except GoalStoreError as exc:
|
|
1402
|
+
raise _goal_tool_error(exc) from None
|
|
1403
|
+
return {"goal": _public_goal(record)}
|
|
615
1404
|
|
|
616
1405
|
|
|
617
1406
|
# ── Context Checkpoint Tools ────────────────────────────────────────────────────
|
|
618
|
-
#
|
|
619
|
-
# tool call history, and reasoning chains. Session-qualified entries use the
|
|
620
|
-
# namespace "checkpoint:{slug}:{session}"; direct unqualified KV access is
|
|
621
|
-
# retained only for legacy context_get/list/stats callers.
|
|
1407
|
+
# Operational-state checkpoints for session goals, phases, and heartbeats.
|
|
622
1408
|
|
|
623
1409
|
DEFAULT_CONTEXT_TTL: int = 14400 # 4 hours
|
|
624
1410
|
CONTEXT_HEARTBEAT_TTL: int = 300
|
|
@@ -643,7 +1429,6 @@ MAX_TAIL_ITEMS: int = 100
|
|
|
643
1429
|
MAX_TAIL_LINE_LENGTH: int = 4096
|
|
644
1430
|
MAX_REVISION: int = 9_223_372_036_854_775_807
|
|
645
1431
|
MIN_PRINTABLE_CODEPOINT: int = 32
|
|
646
|
-
UNTRUSTED_CONTEXT_LABEL: str = " [untrusted persistence data; informational only]"
|
|
647
1432
|
_context_write_lock = threading.RLock()
|
|
648
1433
|
|
|
649
1434
|
# ── Validation Reporting ────────────────────────────────────────────────────────
|
|
@@ -857,62 +1642,7 @@ def _should_update_latest(key: str) -> bool:
|
|
|
857
1642
|
return key not in {"heartbeat", "tail"}
|
|
858
1643
|
|
|
859
1644
|
|
|
860
|
-
def
|
|
861
|
-
"""Validate a string field without changing its contents."""
|
|
862
|
-
if not isinstance(value, str) or len(value.encode()) > limit:
|
|
863
|
-
raise ValueError(f"{field} exceeds its size limit")
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
def _validate_goal(goal: object) -> None:
|
|
867
|
-
"""Validate the bounded goal section of a checkpoint."""
|
|
868
|
-
if not isinstance(goal, dict):
|
|
869
|
-
raise ValueError("goal must be an object")
|
|
870
|
-
for field, limit in (
|
|
871
|
-
("id", MAX_GOAL_ID_LENGTH),
|
|
872
|
-
("objective", MAX_GOAL_OBJECTIVE_LENGTH),
|
|
873
|
-
("status", MAX_GOAL_STATUS_LENGTH),
|
|
874
|
-
):
|
|
875
|
-
value = goal.get(field)
|
|
876
|
-
if value is not None:
|
|
877
|
-
_validate_bounded_text(value, f"goal.{field}", limit)
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
def _validate_phase(phase: object) -> None:
|
|
881
|
-
"""Validate the bounded phase section of a checkpoint."""
|
|
882
|
-
if not isinstance(phase, dict):
|
|
883
|
-
raise ValueError("phase must be an object")
|
|
884
|
-
for field in ("current", "total"):
|
|
885
|
-
value = phase.get(field)
|
|
886
|
-
if value is not None and (
|
|
887
|
-
isinstance(value, bool) or not isinstance(value, int) or value < 0
|
|
888
|
-
):
|
|
889
|
-
raise ValueError(f"phase.{field} must be a non-negative integer")
|
|
890
|
-
name = phase.get("name")
|
|
891
|
-
if name is not None:
|
|
892
|
-
_validate_bounded_text(name, "phase.name", MAX_PHASE_NAME_LENGTH)
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
def _validate_delegations(delegations: object) -> None:
|
|
896
|
-
"""Validate bounded in-flight delegation records."""
|
|
897
|
-
if not isinstance(delegations, dict):
|
|
898
|
-
raise ValueError("delegations must be an object")
|
|
899
|
-
in_flight = delegations.get("in_flight")
|
|
900
|
-
if in_flight is None:
|
|
901
|
-
return
|
|
902
|
-
if not isinstance(in_flight, list) or len(in_flight) > MAX_DELEGATIONS:
|
|
903
|
-
raise ValueError("delegations.in_flight exceeds its size limit")
|
|
904
|
-
for job in in_flight:
|
|
905
|
-
if not isinstance(job, dict):
|
|
906
|
-
raise ValueError("delegations.in_flight entries must be objects")
|
|
907
|
-
for field in ("alias", "agent", "task_id"):
|
|
908
|
-
value = job.get(field)
|
|
909
|
-
if value is not None:
|
|
910
|
-
_validate_bounded_text(
|
|
911
|
-
value, f"delegations.in_flight.{field}", MAX_DELEGATION_FIELD_LENGTH
|
|
912
|
-
)
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
def _validate_tail(tail: object, payload_bytes: int | None = None) -> list[str]:
|
|
1645
|
+
def _validate_tail(tail: object) -> list[str]:
|
|
916
1646
|
"""Validate bounded serialized tail lines."""
|
|
917
1647
|
if not isinstance(tail, list):
|
|
918
1648
|
raise ValueError("tail must be an array")
|
|
@@ -931,11 +1661,6 @@ def _validate_tail(tail: object, payload_bytes: int | None = None) -> list[str]:
|
|
|
931
1661
|
f"{MAX_TAIL_LINE_LENGTH:,}; remove or shorten tail entries, "
|
|
932
1662
|
"or omit tail"
|
|
933
1663
|
)
|
|
934
|
-
if payload_bytes is not None and payload_bytes > MAX_CONTEXT_CONTENT_BYTES:
|
|
935
|
-
raise ValueError(
|
|
936
|
-
f"tail payload is {payload_bytes:,} UTF-8 bytes; maximum is "
|
|
937
|
-
f"{MAX_CONTEXT_CONTENT_BYTES:,}; remove tail entries or omit tail"
|
|
938
|
-
)
|
|
939
1664
|
tail_bytes = sum(len(line.encode()) for line in tail)
|
|
940
1665
|
if tail_bytes > MAX_CONTEXT_CONTENT_BYTES:
|
|
941
1666
|
raise ValueError(
|
|
@@ -946,27 +1671,11 @@ def _validate_tail(tail: object, payload_bytes: int | None = None) -> list[str]:
|
|
|
946
1671
|
return tail
|
|
947
1672
|
|
|
948
1673
|
|
|
949
|
-
def _validate_heartbeat(heartbeat: object) -> None:
|
|
950
|
-
"""Validate bounded heartbeat metadata."""
|
|
951
|
-
if not isinstance(heartbeat, dict):
|
|
952
|
-
raise ValueError("heartbeat must be an object")
|
|
953
|
-
status = heartbeat.get("status")
|
|
954
|
-
if status is not None:
|
|
955
|
-
_validate_bounded_text(status, "heartbeat.status", MAX_GOAL_STATUS_LENGTH)
|
|
956
|
-
turn_count = heartbeat.get("turn_count")
|
|
957
|
-
if turn_count is not None and (
|
|
958
|
-
isinstance(turn_count, bool)
|
|
959
|
-
or not isinstance(turn_count, int)
|
|
960
|
-
or turn_count < 0
|
|
961
|
-
):
|
|
962
|
-
raise ValueError("heartbeat.turn_count must be a non-negative integer")
|
|
963
|
-
|
|
964
|
-
|
|
965
1674
|
def _validate_version_metadata(version: object) -> None:
|
|
966
1675
|
"""Validate optional checkpoint ``version`` metadata leniently.
|
|
967
1676
|
|
|
968
|
-
``version`` is opaque application metadata
|
|
969
|
-
|
|
1677
|
+
``version`` is opaque application metadata, not a persistence requirement.
|
|
1678
|
+
It may be a positive integer, a JSON float
|
|
970
1679
|
such as ``1.0``, or a version label like ``"1.5.0-beta.2"``. Absent/null
|
|
971
1680
|
versions and any non-empty string remain valid, preserving existing integer
|
|
972
1681
|
checkpoints while allowing forward-compatible labels. Only bools, empty
|
|
@@ -977,7 +1686,7 @@ def _validate_version_metadata(version: object) -> None:
|
|
|
977
1686
|
return
|
|
978
1687
|
if isinstance(version, bool):
|
|
979
1688
|
raise ValueError("version must be a positive integer or version label")
|
|
980
|
-
if isinstance(version,
|
|
1689
|
+
if isinstance(version, int | float):
|
|
981
1690
|
if not 1 <= version < float("inf"):
|
|
982
1691
|
raise ValueError("version must be a positive integer or version label")
|
|
983
1692
|
return
|
|
@@ -985,30 +1694,74 @@ def _validate_version_metadata(version: object) -> None:
|
|
|
985
1694
|
raise ValueError("version must be a positive integer or version label")
|
|
986
1695
|
|
|
987
1696
|
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
)
|
|
1697
|
+
def _validate_checkpoint_text_fields(
|
|
1698
|
+
section: Mapping[str, object],
|
|
1699
|
+
section_name: str,
|
|
1700
|
+
limits: tuple[tuple[str, int], ...],
|
|
1701
|
+
) -> None:
|
|
1702
|
+
for field, limit in limits:
|
|
1703
|
+
value = section.get(field)
|
|
1704
|
+
if value is not None and (
|
|
1705
|
+
not isinstance(value, str) or len(value.encode()) > limit
|
|
1706
|
+
):
|
|
1707
|
+
raise ValueError(f"{section_name}.{field} exceeds its size limit")
|
|
1708
|
+
|
|
1709
|
+
|
|
1710
|
+
def _validate_checkpoint_integer_fields(
|
|
1711
|
+
section: Mapping[str, object], section_name: str, fields: tuple[str, ...]
|
|
1712
|
+
) -> None:
|
|
1713
|
+
for field in fields:
|
|
1714
|
+
value = section.get(field)
|
|
1715
|
+
if value is not None and (
|
|
1716
|
+
isinstance(value, bool) or not isinstance(value, int) or value < 0
|
|
1717
|
+
):
|
|
1718
|
+
raise ValueError(f"{section_name}.{field} must be a non-negative integer")
|
|
998
1719
|
|
|
999
1720
|
|
|
1000
|
-
def
|
|
1001
|
-
|
|
1721
|
+
def _validate_checkpoint_delegations(section: dict) -> None:
|
|
1722
|
+
in_flight = section.get("in_flight")
|
|
1723
|
+
if in_flight is None:
|
|
1724
|
+
return
|
|
1725
|
+
if not isinstance(in_flight, list) or len(in_flight) > MAX_DELEGATIONS:
|
|
1726
|
+
raise ValueError("delegations.in_flight exceeds its size limit")
|
|
1727
|
+
for job in in_flight:
|
|
1728
|
+
if not isinstance(job, dict):
|
|
1729
|
+
raise ValueError("delegations.in_flight entries must be objects")
|
|
1730
|
+
_validate_checkpoint_text_fields(
|
|
1731
|
+
job,
|
|
1732
|
+
"delegations.in_flight",
|
|
1733
|
+
tuple(
|
|
1734
|
+
(field, MAX_DELEGATION_FIELD_LENGTH)
|
|
1735
|
+
for field in ("alias", "agent", "task_id")
|
|
1736
|
+
),
|
|
1737
|
+
)
|
|
1738
|
+
|
|
1002
1739
|
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
|
-
|
|
1011
|
-
|
|
1740
|
+
def _validate_checkpoint_section(field: str, value: object) -> None:
|
|
1741
|
+
if field == "goal":
|
|
1742
|
+
_validate_checkpoint_text_fields(
|
|
1743
|
+
value,
|
|
1744
|
+
field,
|
|
1745
|
+
(
|
|
1746
|
+
("id", MAX_GOAL_ID_LENGTH),
|
|
1747
|
+
("objective", MAX_GOAL_OBJECTIVE_LENGTH),
|
|
1748
|
+
("status", MAX_GOAL_STATUS_LENGTH),
|
|
1749
|
+
),
|
|
1750
|
+
)
|
|
1751
|
+
elif field == "phase":
|
|
1752
|
+
_validate_checkpoint_integer_fields(value, field, ("current", "total"))
|
|
1753
|
+
_validate_checkpoint_text_fields(
|
|
1754
|
+
value, field, (("name", MAX_PHASE_NAME_LENGTH),)
|
|
1755
|
+
)
|
|
1756
|
+
elif field == "delegations":
|
|
1757
|
+
_validate_checkpoint_delegations(value)
|
|
1758
|
+
elif field == "tail":
|
|
1759
|
+
_validate_tail(value)
|
|
1760
|
+
elif field == "heartbeat":
|
|
1761
|
+
_validate_checkpoint_text_fields(
|
|
1762
|
+
value, field, (("status", MAX_GOAL_STATUS_LENGTH),)
|
|
1763
|
+
)
|
|
1764
|
+
_validate_checkpoint_integer_fields(value, field, ("turn_count",))
|
|
1012
1765
|
|
|
1013
1766
|
|
|
1014
1767
|
def _collect_checkpoint_errors(errors: _ArgErrors, parsed: dict, prefix: str) -> None:
|
|
@@ -1018,7 +1771,14 @@ def _collect_checkpoint_errors(errors: _ArgErrors, parsed: dict, prefix: str) ->
|
|
|
1018
1771
|
except ValueError as exc:
|
|
1019
1772
|
errors.reroot(prefix, str(exc))
|
|
1020
1773
|
|
|
1021
|
-
|
|
1774
|
+
sections = (
|
|
1775
|
+
("goal", dict, "an object"),
|
|
1776
|
+
("phase", dict, "an object"),
|
|
1777
|
+
("delegations", dict, "an object"),
|
|
1778
|
+
("tail", list, "an array"),
|
|
1779
|
+
("heartbeat", dict, "an object"),
|
|
1780
|
+
)
|
|
1781
|
+
for field, expected_type, wording in sections:
|
|
1022
1782
|
value = parsed.get(field)
|
|
1023
1783
|
if value is None:
|
|
1024
1784
|
continue
|
|
@@ -1028,7 +1788,7 @@ def _collect_checkpoint_errors(errors: _ArgErrors, parsed: dict, prefix: str) ->
|
|
|
1028
1788
|
)
|
|
1029
1789
|
continue
|
|
1030
1790
|
try:
|
|
1031
|
-
|
|
1791
|
+
_validate_checkpoint_section(field, value)
|
|
1032
1792
|
except ValueError as exc:
|
|
1033
1793
|
errors.reroot(prefix, str(exc))
|
|
1034
1794
|
|
|
@@ -1052,8 +1812,7 @@ def _collect_context_content_errors(
|
|
|
1052
1812
|
try:
|
|
1053
1813
|
parsed = json.loads(content)
|
|
1054
1814
|
except (json.JSONDecodeError, TypeError, ValueError):
|
|
1055
|
-
# Raw text remains a compatibility format
|
|
1056
|
-
# it as a checkpoint. It is still bounded above.
|
|
1815
|
+
# Raw text remains a compatibility format. It is still bounded above.
|
|
1057
1816
|
return
|
|
1058
1817
|
if isinstance(parsed, list) and key == "tail":
|
|
1059
1818
|
try:
|
|
@@ -1093,18 +1852,6 @@ def _collect_scope_error(errors: _ArgErrors, scope: str) -> None:
|
|
|
1093
1852
|
errors.example(SCOPE_EXAMPLE)
|
|
1094
1853
|
|
|
1095
1854
|
|
|
1096
|
-
def _safe_untrusted_text(value: object) -> str:
|
|
1097
|
-
"""Escape control/markup delimiters while preserving untrusted content."""
|
|
1098
|
-
text = str(value)
|
|
1099
|
-
return (
|
|
1100
|
-
text.replace("<", r"\u003c")
|
|
1101
|
-
.replace(">", r"\u003e")
|
|
1102
|
-
.replace("\r", r"\r")
|
|
1103
|
-
.replace("\n", r"\n")
|
|
1104
|
-
.replace("\x00", r"\u0000")
|
|
1105
|
-
)
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
1855
|
def _stored_revision(raw: object) -> int:
|
|
1109
1856
|
"""Parse a context revision; legacy datetime values are revision zero."""
|
|
1110
1857
|
try:
|
|
@@ -1188,7 +1935,7 @@ def _upsert_context_entry(
|
|
|
1188
1935
|
@mcp.tool(
|
|
1189
1936
|
name="context_save",
|
|
1190
1937
|
description="Save a context checkpoint for a session/phase. "
|
|
1191
|
-
"Stores structured
|
|
1938
|
+
"Stores structured operational-state checkpoint data with key-specific expiry. "
|
|
1192
1939
|
"The serialized content is limited to 65,536 UTF-8 bytes. An included "
|
|
1193
1940
|
"tail may contain at most 100 strings, each at most 4,096 UTF-8 bytes, "
|
|
1194
1941
|
"with at most 65,536 UTF-8 bytes across all tail strings. Oversized "
|
|
@@ -1228,11 +1975,9 @@ async def context_save(
|
|
|
1228
1975
|
scope: str = "project",
|
|
1229
1976
|
revision: int | None = None,
|
|
1230
1977
|
) -> dict:
|
|
1231
|
-
"""Save
|
|
1978
|
+
"""Save an operational-state checkpoint for the supplied session ID.
|
|
1232
1979
|
|
|
1233
|
-
|
|
1234
|
-
cross-session reads. The session_id must be supplied by the autonomy
|
|
1235
|
-
caller; this function never generates one.
|
|
1980
|
+
The caller must supply the session ID; this function never generates one.
|
|
1236
1981
|
|
|
1237
1982
|
Every argument is validated before any write, and all violations are
|
|
1238
1983
|
reported in a single error so the caller fixes them in one round-trip.
|
|
@@ -1241,13 +1986,13 @@ async def context_save(
|
|
|
1241
1986
|
slug: Session identifier (e.g. "auth-refactor").
|
|
1242
1987
|
key: Checkpoint key (e.g. "phase:3", "latest", "heartbeat").
|
|
1243
1988
|
content: JSON-serializable string or any text content.
|
|
1244
|
-
session_id: Required
|
|
1989
|
+
session_id: Required session ID associated with this checkpoint.
|
|
1245
1990
|
ttl: TTL in seconds (defaults to the key-specific context policy).
|
|
1246
1991
|
scope: 'project' (default) or 'global'.
|
|
1247
1992
|
revision: Optional monotonic revision. Older/equal revisions are no-ops.
|
|
1248
1993
|
|
|
1249
1994
|
Returns:
|
|
1250
|
-
Status dict with
|
|
1995
|
+
Status dict with checkpoint key and session ID for subsequent calls.
|
|
1251
1996
|
"""
|
|
1252
1997
|
errors = _ArgErrors("context_save")
|
|
1253
1998
|
valid_slug = _collect_identifier(errors, slug, "slug", MAX_CONTEXT_SLUG_LENGTH)
|
|
@@ -1340,14 +2085,13 @@ async def context_get(
|
|
|
1340
2085
|
legacy: bool = False,
|
|
1341
2086
|
scope: str = "project",
|
|
1342
2087
|
) -> str | None:
|
|
1343
|
-
"""Get
|
|
2088
|
+
"""Get an operational-state checkpoint by slug and key.
|
|
1344
2089
|
|
|
1345
2090
|
Args:
|
|
1346
2091
|
slug: Session identifier.
|
|
1347
2092
|
key: Checkpoint key (default "latest").
|
|
1348
2093
|
session_id: Required for session-scoped reads.
|
|
1349
|
-
legacy: Explicitly opt into the
|
|
1350
|
-
session_id is available.
|
|
2094
|
+
legacy: Explicitly opt into reading the pre-session checkpoint format.
|
|
1351
2095
|
scope: 'project' (default) or 'global'.
|
|
1352
2096
|
|
|
1353
2097
|
Returns:
|
|
@@ -1371,507 +2115,6 @@ async def context_get(
|
|
|
1371
2115
|
return row[0] if row else None
|
|
1372
2116
|
|
|
1373
2117
|
|
|
1374
|
-
@mcp.tool(
|
|
1375
|
-
name="context_list",
|
|
1376
|
-
description="List all context checkpoints for a session slug. "
|
|
1377
|
-
"Returns keys, timestamps, and TTL info.",
|
|
1378
|
-
)
|
|
1379
|
-
async def context_list(
|
|
1380
|
-
slug: str,
|
|
1381
|
-
session_id: str | None = None,
|
|
1382
|
-
legacy: bool = False,
|
|
1383
|
-
scope: str = "project",
|
|
1384
|
-
) -> list[dict]:
|
|
1385
|
-
"""List all checkpoints for a session.
|
|
1386
|
-
|
|
1387
|
-
Args:
|
|
1388
|
-
slug: Session identifier.
|
|
1389
|
-
session_id: Required for session-scoped reads.
|
|
1390
|
-
legacy: Explicitly opt into the unqualified legacy namespace when no
|
|
1391
|
-
session_id is available.
|
|
1392
|
-
scope: 'project' (default) or 'global'.
|
|
1393
|
-
|
|
1394
|
-
Returns:
|
|
1395
|
-
List of dicts with key, created_at, expires_at.
|
|
1396
|
-
"""
|
|
1397
|
-
conn = _db(scope)
|
|
1398
|
-
ns = _context_namespace(slug, session_id, legacy=legacy)
|
|
1399
|
-
if ns is None:
|
|
1400
|
-
return []
|
|
1401
|
-
rows = conn.execute(
|
|
1402
|
-
"SELECT key, created_at, expires_at FROM kv_store "
|
|
1403
|
-
"WHERE namespace = ? "
|
|
1404
|
-
"AND (expires_at IS NULL OR julianday(expires_at) > julianday('now')) "
|
|
1405
|
-
"AND deleted_at IS NULL "
|
|
1406
|
-
"ORDER BY created_at DESC LIMIT 50",
|
|
1407
|
-
(ns,),
|
|
1408
|
-
).fetchall()
|
|
1409
|
-
return [
|
|
1410
|
-
{
|
|
1411
|
-
"key": r[0],
|
|
1412
|
-
"created_at": r[1],
|
|
1413
|
-
"expires_at": r[2],
|
|
1414
|
-
}
|
|
1415
|
-
for r in rows
|
|
1416
|
-
]
|
|
1417
|
-
|
|
1418
|
-
|
|
1419
|
-
@mcp.tool(
|
|
1420
|
-
name="context_stats",
|
|
1421
|
-
description="Return session context statistics: "
|
|
1422
|
-
"checkpoint count, TTL remaining, total size per slug.",
|
|
1423
|
-
)
|
|
1424
|
-
async def context_stats(
|
|
1425
|
-
slug: str,
|
|
1426
|
-
session_id: str | None = None,
|
|
1427
|
-
legacy: bool = False,
|
|
1428
|
-
scope: str = "project",
|
|
1429
|
-
) -> dict:
|
|
1430
|
-
"""Return storage statistics for a session's context.
|
|
1431
|
-
|
|
1432
|
-
Args:
|
|
1433
|
-
slug: Session identifier.
|
|
1434
|
-
session_id: Required for session-scoped reads.
|
|
1435
|
-
legacy: Explicitly opt into the unqualified legacy namespace when no
|
|
1436
|
-
session_id is available.
|
|
1437
|
-
scope: 'project' (default) or 'global'.
|
|
1438
|
-
|
|
1439
|
-
Returns:
|
|
1440
|
-
Dict with entry_count, total_bytes, ttl_remaining.
|
|
1441
|
-
"""
|
|
1442
|
-
conn = _db(scope)
|
|
1443
|
-
ns = _context_namespace(slug, session_id, legacy=legacy)
|
|
1444
|
-
if ns is None:
|
|
1445
|
-
return {
|
|
1446
|
-
"slug": slug,
|
|
1447
|
-
"namespace": None,
|
|
1448
|
-
"entry_count": 0,
|
|
1449
|
-
"expired_entries": 0,
|
|
1450
|
-
"total_bytes": 0,
|
|
1451
|
-
"ttl_remaining_seconds": None,
|
|
1452
|
-
}
|
|
1453
|
-
|
|
1454
|
-
count = conn.execute(
|
|
1455
|
-
"SELECT COUNT(*) FROM kv_store "
|
|
1456
|
-
"WHERE namespace = ? AND deleted_at IS NULL "
|
|
1457
|
-
"AND (expires_at IS NULL OR julianday(expires_at) > julianday('now'))",
|
|
1458
|
-
(ns,),
|
|
1459
|
-
).fetchone()[0]
|
|
1460
|
-
|
|
1461
|
-
expired = conn.execute(
|
|
1462
|
-
"SELECT COUNT(*) FROM kv_store "
|
|
1463
|
-
"WHERE namespace = ? AND expires_at IS NOT NULL "
|
|
1464
|
-
"AND julianday(expires_at) <= julianday('now') "
|
|
1465
|
-
"AND deleted_at IS NULL",
|
|
1466
|
-
(ns,),
|
|
1467
|
-
).fetchone()[0]
|
|
1468
|
-
|
|
1469
|
-
size = conn.execute(
|
|
1470
|
-
"SELECT COALESCE(SUM(LENGTH(value)), 0) FROM kv_store "
|
|
1471
|
-
"WHERE namespace = ? AND deleted_at IS NULL "
|
|
1472
|
-
"AND (expires_at IS NULL OR julianday(expires_at) > julianday('now'))",
|
|
1473
|
-
(ns,),
|
|
1474
|
-
).fetchone()[0]
|
|
1475
|
-
|
|
1476
|
-
# Check TTL of latest entry
|
|
1477
|
-
remaining: int | None = None
|
|
1478
|
-
row = conn.execute(
|
|
1479
|
-
"SELECT expires_at FROM kv_store "
|
|
1480
|
-
"WHERE namespace = ? AND key = 'latest' AND deleted_at IS NULL",
|
|
1481
|
-
(ns,),
|
|
1482
|
-
).fetchone()
|
|
1483
|
-
if row and row[0]:
|
|
1484
|
-
try:
|
|
1485
|
-
exp = datetime.fromisoformat(row[0])
|
|
1486
|
-
now = datetime.now(UTC)
|
|
1487
|
-
remaining = max(0, int((exp - now).total_seconds()))
|
|
1488
|
-
except (ValueError, TypeError):
|
|
1489
|
-
pass
|
|
1490
|
-
|
|
1491
|
-
return {
|
|
1492
|
-
"slug": slug,
|
|
1493
|
-
"namespace": ns,
|
|
1494
|
-
"entry_count": count,
|
|
1495
|
-
"expired_entries": expired,
|
|
1496
|
-
"total_bytes": size,
|
|
1497
|
-
"ttl_remaining_seconds": remaining,
|
|
1498
|
-
}
|
|
1499
|
-
|
|
1500
|
-
|
|
1501
|
-
# ── Post-Compaction Injector (WS2 PR #94) ─────────────────────────────────────
|
|
1502
|
-
# Deterministic rehydration after a native compaction event: a long session
|
|
1503
|
-
# reads ``latest`` + serialized ``tail`` from
|
|
1504
|
-
# ``checkpoint:<slug>:<session_id>`` and
|
|
1505
|
-
# rebuilds its critical context (active goal, in-flight delegations,
|
|
1506
|
-
# current phase) WITHOUT any LLM call or generative embedding.
|
|
1507
|
-
#
|
|
1508
|
-
# Checkpoint JSON convention (written by Zeus via context_save):
|
|
1509
|
-
# {"version": 1,
|
|
1510
|
-
# "goal": {"id": ..., "objective": ..., "status": ...},
|
|
1511
|
-
# "phase": {"current": ..., "total": ..., "name": ...},
|
|
1512
|
-
# "delegations": {"in_flight": [{"alias": ..., "agent": ..., "task_id": ...}]},
|
|
1513
|
-
# "tail": ["phase:1 ...", ...], # serialized last-N phase digests
|
|
1514
|
-
# "heartbeat": {...}}
|
|
1515
|
-
# ``tail`` may also live under a separate ``tail`` key (JSON array).
|
|
1516
|
-
#
|
|
1517
|
-
# Guarantees: required session_id, kill-switch PANTHEON_COMPACTION=off,
|
|
1518
|
-
# TTL-respecting reads, no sibling fallback, conditional heartbeat TTL refresh,
|
|
1519
|
-
# and idempotent recovery (no checkpoint rows are added or duplicated).
|
|
1520
|
-
|
|
1521
|
-
COMPACTION_KILL_SWITCH_ENV: str = "PANTHEON_COMPACTION"
|
|
1522
|
-
SESSION_END_SUMMARY_ENV: str = "PANTHEON_SESSION_END_SUMMARY"
|
|
1523
|
-
REHYDRATE_TAIL_CAP: int = 10
|
|
1524
|
-
SUMMARY_TAIL_CAP: int = 5
|
|
1525
|
-
|
|
1526
|
-
|
|
1527
|
-
def _compaction_disabled() -> bool:
|
|
1528
|
-
"""True when the PANTHEON_COMPACTION kill-switch is off."""
|
|
1529
|
-
return os.environ.get(COMPACTION_KILL_SWITCH_ENV, "").lower() == "off"
|
|
1530
|
-
|
|
1531
|
-
|
|
1532
|
-
def _read_checkpoint_value(
|
|
1533
|
-
conn: sqlite3.Connection, namespace: str, key: str
|
|
1534
|
-
) -> str | None:
|
|
1535
|
-
"""Read one unexpired, non-deleted checkpoint value (None when absent)."""
|
|
1536
|
-
row = conn.execute(
|
|
1537
|
-
"SELECT value FROM kv_store "
|
|
1538
|
-
"WHERE namespace = ? AND key = ? "
|
|
1539
|
-
"AND (expires_at IS NULL OR julianday(expires_at) > julianday('now')) "
|
|
1540
|
-
"AND deleted_at IS NULL",
|
|
1541
|
-
(namespace, key),
|
|
1542
|
-
).fetchone()
|
|
1543
|
-
return row[0] if row else None
|
|
1544
|
-
|
|
1545
|
-
|
|
1546
|
-
def _parse_checkpoint(content: str) -> dict | None:
|
|
1547
|
-
"""Parse and validate one checkpoint; invalid JSON fails closed."""
|
|
1548
|
-
if len(content.encode()) > MAX_CONTEXT_CONTENT_BYTES:
|
|
1549
|
-
return None
|
|
1550
|
-
try:
|
|
1551
|
-
data = json.loads(content)
|
|
1552
|
-
except (json.JSONDecodeError, TypeError, ValueError):
|
|
1553
|
-
return None
|
|
1554
|
-
if not isinstance(data, dict):
|
|
1555
|
-
return None
|
|
1556
|
-
try:
|
|
1557
|
-
_validate_checkpoint_shape(data)
|
|
1558
|
-
except ValueError:
|
|
1559
|
-
return None
|
|
1560
|
-
return data
|
|
1561
|
-
|
|
1562
|
-
|
|
1563
|
-
def _checkpoint_tail(checkpoint: dict, tail_raw: str | None) -> list[str]:
|
|
1564
|
-
"""Tail lines from embedded ``tail`` with fallback to the ``tail`` key."""
|
|
1565
|
-
tail = checkpoint.get("tail")
|
|
1566
|
-
if isinstance(tail, list):
|
|
1567
|
-
try:
|
|
1568
|
-
lines = _validate_tail(tail)
|
|
1569
|
-
except ValueError:
|
|
1570
|
-
return []
|
|
1571
|
-
elif isinstance(tail_raw, str):
|
|
1572
|
-
if len(tail_raw.encode()) > MAX_CONTEXT_CONTENT_BYTES:
|
|
1573
|
-
return []
|
|
1574
|
-
try:
|
|
1575
|
-
parsed = json.loads(tail_raw)
|
|
1576
|
-
lines = _validate_tail(parsed, payload_bytes=len(tail_raw.encode()))
|
|
1577
|
-
except (json.JSONDecodeError, TypeError, ValueError):
|
|
1578
|
-
return []
|
|
1579
|
-
else:
|
|
1580
|
-
lines = []
|
|
1581
|
-
return [line for line in lines if line.strip()][:REHYDRATE_TAIL_CAP]
|
|
1582
|
-
|
|
1583
|
-
|
|
1584
|
-
def _mission_block(checkpoint: dict) -> str | None:
|
|
1585
|
-
"""<mission_context> for a non-done goal (done goals stay buried)."""
|
|
1586
|
-
goal = checkpoint.get("goal")
|
|
1587
|
-
if not isinstance(goal, dict):
|
|
1588
|
-
return None
|
|
1589
|
-
status = str(goal.get("status", ""))
|
|
1590
|
-
objective = str(goal.get("objective", "")).strip()
|
|
1591
|
-
if status == "done" or not objective:
|
|
1592
|
-
return None
|
|
1593
|
-
gid = str(goal.get("id", "goal")).strip() or "goal"
|
|
1594
|
-
return (
|
|
1595
|
-
f"<mission_context>\n{UNTRUSTED_CONTEXT_LABEL}\n"
|
|
1596
|
-
f" [{_safe_untrusted_text(gid)}] {_safe_untrusted_text(objective)}"
|
|
1597
|
-
f" — {_safe_untrusted_text(status)}"
|
|
1598
|
-
)
|
|
1599
|
-
|
|
1600
|
-
|
|
1601
|
-
def _phase_block(checkpoint: dict) -> str | None:
|
|
1602
|
-
"""<phase_context> for the current phase (omitted when unknown)."""
|
|
1603
|
-
phase = checkpoint.get("phase")
|
|
1604
|
-
if not isinstance(phase, dict) or phase.get("current") is None:
|
|
1605
|
-
return None
|
|
1606
|
-
total = phase.get("total")
|
|
1607
|
-
current = phase.get("current")
|
|
1608
|
-
span = f"{current}/{total}" if total is not None else str(current)
|
|
1609
|
-
name = str(phase.get("name", "")).strip()
|
|
1610
|
-
line = f" phase {_safe_untrusted_text(span)}"
|
|
1611
|
-
if name:
|
|
1612
|
-
line += f" — {_safe_untrusted_text(name)}"
|
|
1613
|
-
return f"<phase_context>\n{UNTRUSTED_CONTEXT_LABEL}\n{line}"
|
|
1614
|
-
|
|
1615
|
-
|
|
1616
|
-
def _delegation_block(checkpoint: dict) -> str | None:
|
|
1617
|
-
"""<delegation_context> for in-flight delegations (never capped)."""
|
|
1618
|
-
delegations = checkpoint.get("delegations")
|
|
1619
|
-
if not isinstance(delegations, dict):
|
|
1620
|
-
return None
|
|
1621
|
-
in_flight = delegations.get("in_flight")
|
|
1622
|
-
if not isinstance(in_flight, list):
|
|
1623
|
-
return None
|
|
1624
|
-
lines = []
|
|
1625
|
-
for job in in_flight:
|
|
1626
|
-
if not isinstance(job, dict):
|
|
1627
|
-
continue
|
|
1628
|
-
alias = str(job.get("alias") or job.get("task_id") or "?").strip()
|
|
1629
|
-
agent = str(job.get("agent", "?")).strip()
|
|
1630
|
-
task_id = str(job.get("task_id", "")).strip()
|
|
1631
|
-
detail = (
|
|
1632
|
-
f" — {_safe_untrusted_text(task_id)}"
|
|
1633
|
-
if task_id and task_id != alias
|
|
1634
|
-
else ""
|
|
1635
|
-
)
|
|
1636
|
-
lines.append(
|
|
1637
|
-
f" [{_safe_untrusted_text(alias)}] {_safe_untrusted_text(agent)}"
|
|
1638
|
-
f"{detail} [in-flight]"
|
|
1639
|
-
)
|
|
1640
|
-
if not lines:
|
|
1641
|
-
return None
|
|
1642
|
-
return "<delegation_context>\n" + UNTRUSTED_CONTEXT_LABEL + "\n" + "\n".join(lines)
|
|
1643
|
-
|
|
1644
|
-
|
|
1645
|
-
def _tail_block(checkpoint: dict) -> str | None:
|
|
1646
|
-
"""<tail_context> for the serialized tail (already capped on load)."""
|
|
1647
|
-
tail_lines = checkpoint.get("_tail_raw")
|
|
1648
|
-
try:
|
|
1649
|
-
validated_lines = _validate_tail(tail_lines)
|
|
1650
|
-
except ValueError:
|
|
1651
|
-
return None
|
|
1652
|
-
if not validated_lines:
|
|
1653
|
-
return None
|
|
1654
|
-
quoted = "\n".join(f" - {_safe_untrusted_text(line)}" for line in validated_lines)
|
|
1655
|
-
return f"<tail_context>\n{UNTRUSTED_CONTEXT_LABEL}\n{quoted}"
|
|
1656
|
-
|
|
1657
|
-
|
|
1658
|
-
def build_rehydration_blocks(checkpoint: dict) -> list[str] | None:
|
|
1659
|
-
"""Build deterministic rehydration blocks from a checkpoint dict.
|
|
1660
|
-
|
|
1661
|
-
Pure string templating — no LLM, no embeddings. Mirrors the
|
|
1662
|
-
``<mission_context>`` convention of the compaction-context builder: only a
|
|
1663
|
-
non-done goal is re-emitted. Returns None when nothing critical remains.
|
|
1664
|
-
"""
|
|
1665
|
-
if not isinstance(checkpoint, dict) or not checkpoint:
|
|
1666
|
-
return None
|
|
1667
|
-
blocks = [
|
|
1668
|
-
block
|
|
1669
|
-
for block in (
|
|
1670
|
-
_mission_block(checkpoint),
|
|
1671
|
-
_phase_block(checkpoint),
|
|
1672
|
-
_delegation_block(checkpoint),
|
|
1673
|
-
_tail_block(checkpoint),
|
|
1674
|
-
)
|
|
1675
|
-
if block is not None
|
|
1676
|
-
]
|
|
1677
|
-
return blocks if blocks else None
|
|
1678
|
-
|
|
1679
|
-
|
|
1680
|
-
def build_session_end_summary(checkpoint: dict) -> str | None:
|
|
1681
|
-
"""Build the Tier 2 session-end summary deterministically (no LLM).
|
|
1682
|
-
|
|
1683
|
-
Fires automatically at session end — no Themis approval gate. Returns
|
|
1684
|
-
None when the checkpoint carries nothing worth compressing.
|
|
1685
|
-
"""
|
|
1686
|
-
if not isinstance(checkpoint, dict) or not checkpoint:
|
|
1687
|
-
return None
|
|
1688
|
-
parts: list[str] = []
|
|
1689
|
-
|
|
1690
|
-
goal = checkpoint.get("goal")
|
|
1691
|
-
if isinstance(goal, dict):
|
|
1692
|
-
objective = str(goal.get("objective", "")).strip()
|
|
1693
|
-
if objective:
|
|
1694
|
-
parts.append(
|
|
1695
|
-
f"Goal: {_safe_untrusted_text(objective)} "
|
|
1696
|
-
f"({_safe_untrusted_text(goal.get('status', '?'))})"
|
|
1697
|
-
)
|
|
1698
|
-
|
|
1699
|
-
phase = checkpoint.get("phase")
|
|
1700
|
-
if isinstance(phase, dict) and phase.get("current") is not None:
|
|
1701
|
-
total = phase.get("total")
|
|
1702
|
-
span = (
|
|
1703
|
-
f"{phase.get('current')}/{total}"
|
|
1704
|
-
if total is not None
|
|
1705
|
-
else phase.get("current")
|
|
1706
|
-
)
|
|
1707
|
-
name = str(phase.get("name", "")).strip()
|
|
1708
|
-
parts.append(
|
|
1709
|
-
f"Phase: {_safe_untrusted_text(span)}"
|
|
1710
|
-
+ (f" {_safe_untrusted_text(name)}" if name else "")
|
|
1711
|
-
)
|
|
1712
|
-
|
|
1713
|
-
delegations = checkpoint.get("delegations")
|
|
1714
|
-
if isinstance(delegations, dict):
|
|
1715
|
-
in_flight = delegations.get("in_flight")
|
|
1716
|
-
if isinstance(in_flight, list):
|
|
1717
|
-
aliases = [
|
|
1718
|
-
_safe_untrusted_text(str(job.get("alias") or job.get("task_id") or "?"))
|
|
1719
|
-
for job in in_flight
|
|
1720
|
-
if isinstance(job, dict)
|
|
1721
|
-
]
|
|
1722
|
-
if aliases:
|
|
1723
|
-
parts.append(f"In-flight: {', '.join(aliases)}")
|
|
1724
|
-
|
|
1725
|
-
tail_raw = checkpoint.get("_tail_raw")
|
|
1726
|
-
if isinstance(tail_raw, list) and tail_raw:
|
|
1727
|
-
kept = [_safe_untrusted_text(str(line)) for line in tail_raw[:SUMMARY_TAIL_CAP]]
|
|
1728
|
-
parts.append("Tail: " + " | ".join(kept))
|
|
1729
|
-
|
|
1730
|
-
if not parts:
|
|
1731
|
-
return None
|
|
1732
|
-
return "# Session summary (Tier 2 auto — no approval gate)\n" + "\n".join(
|
|
1733
|
-
f"- {part}" for part in parts
|
|
1734
|
-
)
|
|
1735
|
-
|
|
1736
|
-
|
|
1737
|
-
def _load_checkpoint_for_rehydrate(
|
|
1738
|
-
conn: sqlite3.Connection, namespace: str
|
|
1739
|
-
) -> dict | None:
|
|
1740
|
-
"""Load exactly ``latest``; expired, malformed, or empty data fails closed."""
|
|
1741
|
-
tail_raw = _read_checkpoint_value(conn, namespace, "tail")
|
|
1742
|
-
raw = _read_checkpoint_value(conn, namespace, "latest")
|
|
1743
|
-
if raw is None:
|
|
1744
|
-
return None
|
|
1745
|
-
checkpoint = _parse_checkpoint(raw)
|
|
1746
|
-
if checkpoint is None:
|
|
1747
|
-
return None
|
|
1748
|
-
checkpoint["_tail_raw"] = _checkpoint_tail(checkpoint, tail_raw)
|
|
1749
|
-
return checkpoint if build_rehydration_blocks(checkpoint) is not None else None
|
|
1750
|
-
|
|
1751
|
-
|
|
1752
|
-
def _refresh_heartbeat_ttl(conn: sqlite3.Connection, namespace: str) -> None:
|
|
1753
|
-
"""Extend an unexpired heartbeat TTL; never shorten, never resurrect."""
|
|
1754
|
-
row = conn.execute(
|
|
1755
|
-
"SELECT expires_at FROM kv_store "
|
|
1756
|
-
"WHERE namespace = ? AND key = 'heartbeat' "
|
|
1757
|
-
"AND (expires_at IS NULL OR julianday(expires_at) > julianday('now')) "
|
|
1758
|
-
"AND deleted_at IS NULL",
|
|
1759
|
-
(namespace,),
|
|
1760
|
-
).fetchone()
|
|
1761
|
-
if not row or not row[0]:
|
|
1762
|
-
return
|
|
1763
|
-
try:
|
|
1764
|
-
current_exp = datetime.fromisoformat(row[0])
|
|
1765
|
-
except (ValueError, TypeError):
|
|
1766
|
-
return
|
|
1767
|
-
now = datetime.now(UTC)
|
|
1768
|
-
if current_exp.tzinfo is None:
|
|
1769
|
-
current_exp = current_exp.replace(tzinfo=UTC)
|
|
1770
|
-
fresh_exp = now + timedelta(seconds=CONTEXT_HEARTBEAT_TTL)
|
|
1771
|
-
if fresh_exp <= current_exp:
|
|
1772
|
-
return
|
|
1773
|
-
revision = _next_context_revision(conn, namespace, "heartbeat")
|
|
1774
|
-
cursor = conn.execute(
|
|
1775
|
-
"UPDATE kv_store SET expires_at = ?, updated_at = datetime('now'), "
|
|
1776
|
-
"revision = ? "
|
|
1777
|
-
"WHERE namespace = ? AND key = 'heartbeat' AND expires_at = ? "
|
|
1778
|
-
"AND (expires_at IS NULL OR julianday(expires_at) > julianday('now')) "
|
|
1779
|
-
"AND deleted_at IS NULL",
|
|
1780
|
-
(fresh_exp.isoformat(), revision, namespace, row[0]),
|
|
1781
|
-
)
|
|
1782
|
-
if cursor.rowcount:
|
|
1783
|
-
conn.commit()
|
|
1784
|
-
|
|
1785
|
-
|
|
1786
|
-
@mcp.tool(
|
|
1787
|
-
name="context_rehydrate",
|
|
1788
|
-
description="Rehydrate critical context after native compaction. "
|
|
1789
|
-
"Reads 'latest' + serialized 'tail' from a session-qualified checkpoint "
|
|
1790
|
-
"namespace and rebuilds "
|
|
1791
|
-
"goal/phase/delegation blocks deterministically (no LLM). Refreshes the "
|
|
1792
|
-
"heartbeat TTL. Requires session_id and honors PANTHEON_COMPACTION=off.",
|
|
1793
|
-
)
|
|
1794
|
-
async def context_rehydrate(
|
|
1795
|
-
slug: str,
|
|
1796
|
-
session_id: str,
|
|
1797
|
-
scope: str = "project",
|
|
1798
|
-
) -> list[str] | None:
|
|
1799
|
-
"""Rehydrate one known session; missing IDs fail closed."""
|
|
1800
|
-
if _compaction_disabled():
|
|
1801
|
-
return None
|
|
1802
|
-
normalized_session = _normalize_session_id(session_id)
|
|
1803
|
-
errors = _ArgErrors("context_rehydrate")
|
|
1804
|
-
valid_slug = _collect_identifier(errors, slug, "slug", MAX_CONTEXT_SLUG_LENGTH)
|
|
1805
|
-
if normalized_session is None:
|
|
1806
|
-
errors.add("session_id", "is required and must be non-empty")
|
|
1807
|
-
errors.example(SESSION_ID_EXAMPLE)
|
|
1808
|
-
valid_session = None
|
|
1809
|
-
else:
|
|
1810
|
-
valid_session = _collect_identifier(
|
|
1811
|
-
errors, normalized_session, "session_id", MAX_CONTEXT_SESSION_ID_LENGTH
|
|
1812
|
-
)
|
|
1813
|
-
_collect_scope_error(errors, scope)
|
|
1814
|
-
errors.raise_if_any()
|
|
1815
|
-
conn = _db(scope)
|
|
1816
|
-
namespace = f"checkpoint:{valid_slug}:{valid_session}"
|
|
1817
|
-
checkpoint = _load_checkpoint_for_rehydrate(conn, namespace)
|
|
1818
|
-
if checkpoint is None:
|
|
1819
|
-
return None
|
|
1820
|
-
blocks = build_rehydration_blocks(checkpoint)
|
|
1821
|
-
if blocks is None:
|
|
1822
|
-
return None
|
|
1823
|
-
_refresh_heartbeat_ttl(conn, namespace)
|
|
1824
|
-
return blocks
|
|
1825
|
-
|
|
1826
|
-
|
|
1827
|
-
@mcp.tool(
|
|
1828
|
-
name="context_session_summary",
|
|
1829
|
-
description="Tier 2 session-end summary without Themis approval. "
|
|
1830
|
-
"Compresses the checkpoint (goal, phase, in-flight, tail) into a "
|
|
1831
|
-
"memory-bank-ready summary deterministically (no LLM). "
|
|
1832
|
-
"Requires session_id. Opt-out via PANTHEON_SESSION_END_SUMMARY=off.",
|
|
1833
|
-
)
|
|
1834
|
-
async def context_session_summary(
|
|
1835
|
-
slug: str,
|
|
1836
|
-
session_id: str,
|
|
1837
|
-
scope: str = "project",
|
|
1838
|
-
) -> str | None:
|
|
1839
|
-
"""Summarize one known session; missing IDs fail closed."""
|
|
1840
|
-
if os.environ.get(SESSION_END_SUMMARY_ENV, "").lower() == "off":
|
|
1841
|
-
return None
|
|
1842
|
-
normalized_session = _normalize_session_id(session_id)
|
|
1843
|
-
errors = _ArgErrors("context_session_summary")
|
|
1844
|
-
valid_slug = _collect_identifier(errors, slug, "slug", MAX_CONTEXT_SLUG_LENGTH)
|
|
1845
|
-
if normalized_session is None:
|
|
1846
|
-
errors.add("session_id", "is required and must be non-empty")
|
|
1847
|
-
errors.example(SESSION_ID_EXAMPLE)
|
|
1848
|
-
valid_session = None
|
|
1849
|
-
else:
|
|
1850
|
-
valid_session = _collect_identifier(
|
|
1851
|
-
errors, normalized_session, "session_id", MAX_CONTEXT_SESSION_ID_LENGTH
|
|
1852
|
-
)
|
|
1853
|
-
_collect_scope_error(errors, scope)
|
|
1854
|
-
errors.raise_if_any()
|
|
1855
|
-
conn = _db(scope)
|
|
1856
|
-
namespace = f"checkpoint:{valid_slug}:{valid_session}"
|
|
1857
|
-
checkpoint = _load_checkpoint_for_rehydrate(conn, namespace)
|
|
1858
|
-
if checkpoint is None:
|
|
1859
|
-
return None
|
|
1860
|
-
return build_session_end_summary(checkpoint)
|
|
1861
|
-
|
|
1862
|
-
|
|
1863
|
-
def _resolve_db_path(scope: str) -> Path | None:
|
|
1864
|
-
"""Resolve the database file path for a given scope.
|
|
1865
|
-
|
|
1866
|
-
Returns the actual path used at init (honoring an explicit
|
|
1867
|
-
``--project-db``), so deletelog writes and db_size stats land next to
|
|
1868
|
-
the real database file.
|
|
1869
|
-
"""
|
|
1870
|
-
if scope == "global":
|
|
1871
|
-
return _global_root / "global.db"
|
|
1872
|
-
return _project_db_path
|
|
1873
|
-
|
|
1874
|
-
|
|
1875
2118
|
# ── Main Entrypoint ─────────────────────────────────────────────────────────────
|
|
1876
2119
|
|
|
1877
2120
|
if __name__ == "__main__":
|