pantheon-opencode 1.6.0-beta.15 → 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.
Files changed (39) hide show
  1. package/CHANGELOG.md +33 -3
  2. package/README.md +120 -26
  3. package/README.pt-BR.md +14 -14
  4. package/package.json +3 -3
  5. package/plugin.json +1 -1
  6. package/pyproject.toml +1 -1
  7. package/scripts/_pantheon_paths.py +24 -0
  8. package/scripts/doctor.mjs +7 -2
  9. package/scripts/install-mcp.mjs +1 -1
  10. package/scripts/mcp_persistence.py +1260 -1017
  11. package/scripts/memory_mcp.py +12 -843
  12. package/scripts/test-opencode-v2-sandbox.sh +2 -115
  13. package/skills-lock.json +3 -3
  14. package/src/agents/apollo.md +1 -2
  15. package/src/agents/athena.md +1 -2
  16. package/src/agents/gaia.md +0 -1
  17. package/src/agents/hermes.md +1 -1
  18. package/src/agents/iris.md +0 -1
  19. package/src/agents/mnemosyne.md +3 -2
  20. package/src/agents/zeus.md +1 -1
  21. package/src/mcp/_pantheon_paths.py +24 -0
  22. package/src/mcp/mcp_codemap_module.py +86 -18
  23. package/src/mcp/mcp_persistence.py +1260 -1017
  24. package/src/mcp/memory_mcp.py +101 -57
  25. package/src/pantheon/goal-loop.ts +11 -8
  26. package/src/pantheon/task-result-guard.ts +38 -2
  27. package/src/pantheon/v2-execute-after.ts +117 -20
  28. package/src/pantheon/v2-tools.ts +10 -1
  29. package/src/plugin-v2.ts +6 -4
  30. package/src/plugin.ts +3 -2
  31. package/src/plugins/tui/dist/tui-v2.js +2 -2
  32. package/src/plugins/tui/dist/tui.js +1 -1
  33. package/src/plugins/tui/package-lock.json +2 -2
  34. package/src/plugins/tui/package.json +1 -1
  35. package/src/routing.yml +4 -4
  36. package/src/skills/codemap/SKILL.md +1 -1
  37. package/src/skills/memory-bank/SKILL.md +17 -13
  38. package/src/skills/session-goal/SKILL.md +12 -22
  39. 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
- Key-Value store with FTS5 full-text search, TTL-based expiration,
5
- and namespace isolation. Uses SQLite with zero external dependencies.
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
- python scripts/mcp_persistence.py
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 Callable
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, pantheon_project
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, set on TTL purge
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="Key-Value store with FTS5 full-text search, "
87
- "TTL-based expiration, and namespace isolation.",
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. kv_search uses FTS5, which isn't on all systems.
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 not available. kv_search will fail.", file=sys.stderr
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
- # ── Deletelog ────────────────────────────────────────────────────────────────────
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
- # Shift existing rotated files: .3 → remove, .2 → .3, .1 → .2
175
- for i in range(_DELETELOG_KEEP, 0, -1):
176
- older = log_path.with_suffix(f".deletelog.{i}")
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
- # Rename current log to .1
184
- log_path.rename(log_path.with_suffix(".deletelog.1"))
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
- def _write_deletelog(db_path: Path, count: int, keys: list[str]) -> None:
188
- """Append a TTL purge entry to the deletelog."""
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
- parser = argparse.ArgumentParser()
201
- parser.add_argument("--global-db", default=None)
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
- _project_db_instance = None
211
- _project_db_path: Path | None = None
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
- # ── Tools ───────────────────────────────────────────────────────────────────────
224
+ class ActiveGoalExistsError(GoalStoreError):
225
+ """Raised when a session already has an active goal."""
224
226
 
225
227
 
226
- @mcp.tool(
227
- name="kv_store",
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
- Args:
246
- namespace: Logical grouping for keys.
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
- Returns:
253
- Status dict with namespace and key.
254
- """
255
- errors = _ArgErrors("kv_store")
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
- validated_ttl = _validate_ttl(ttl)
258
- except ValueError as exc:
259
- errors.report(str(exc), repr(ttl))
260
- errors.example(TTL_EXAMPLE)
261
- validated_ttl = None
262
- _collect_scope_error(errors, scope)
263
- errors.raise_if_any()
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
- conn.execute(
271
- "INSERT INTO kv_store (namespace, key, value, expires_at, "
272
- "created_at, updated_at) VALUES (?, ?, ?, ?, datetime('now'), datetime('now'))"
273
- "ON CONFLICT(namespace, key) DO UPDATE SET "
274
- " value = excluded.value, "
275
- " expires_at = excluded.expires_at, "
276
- " updated_at = datetime('now')",
277
- (namespace, key, value, expires_at),
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.commit()
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
- return {"status": "stored", "namespace": namespace, "key": key}
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
- @mcp.tool(
288
- name="kv_get",
289
- description="Retrieve a value by namespace and key. "
290
- "Returns None if not found or expired.",
291
- )
292
- async def kv_get(
293
- namespace: str,
294
- key: str,
295
- scope: str = "project",
296
- ) -> str | None:
297
- """Get a value by namespace and key.
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
- Returns:
305
- Value string or None if not found/expired.
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
- conn = _db(scope)
308
- row = conn.execute(
309
- "SELECT value FROM kv_store "
310
- "WHERE namespace = ? AND key = ? "
311
- "AND (expires_at IS NULL OR julianday(expires_at) > julianday('now')) "
312
- "AND deleted_at IS NULL",
313
- (namespace, key),
314
- ).fetchone()
315
- return str(row[0]) if row else None
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
- @mcp.tool(
319
- name="kv_stats",
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
- Returns:
334
- Dict with total_entries, expired_entries, namespaces breakdown, db_size_bytes.
335
- """
336
- conn = _db(scope)
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
- namespaces = {r[0]: {"count": r[1], "expired": r[2]} for r in ns_rows}
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
- return {
360
- "scope": scope,
361
- "total_entries": total,
362
- "expired_entries": expired,
363
- "namespaces": namespaces,
364
- "db_size_bytes": db_size,
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
- @mcp.tool(
369
- name="kv_delete",
370
- description="Delete a key-value pair by namespace and key. "
371
- "FTS trigger cascades automatically.",
372
- )
373
- async def kv_delete(
374
- namespace: str,
375
- key: str,
376
- scope: str = "project",
377
- ) -> dict:
378
- """Delete a key-value pair.
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
- Returns:
386
- Status dict indicating deletion outcome.
387
- """
388
- conn = _db(scope)
389
- cursor = conn.execute(
390
- "DELETE FROM kv_store WHERE namespace = ? AND key = ?",
391
- (namespace, key),
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
- @mcp.tool(
400
- name="kv_list",
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
- Args:
413
- namespace: Logical grouping for keys.
414
- prefix: Optional key prefix filter.
415
- scope: 'project' (default) or 'global'.
416
- limit: Maximum number of results (default 100).
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
- Returns:
419
- List of dicts with key, value, created_at, expires_at.
420
- """
421
- conn = _db(scope)
422
- rows = conn.execute(
423
- "SELECT key, value, created_at, expires_at FROM kv_store "
424
- "WHERE namespace = ? AND key LIKE ? "
425
- "AND (expires_at IS NULL OR julianday(expires_at) > julianday('now')) "
426
- "AND deleted_at IS NULL "
427
- "ORDER BY key LIMIT ?",
428
- (namespace, f"{prefix}%", limit),
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
- return [
431
- {
432
- "key": r[0],
433
- "value": r[1],
434
- "created_at": r[2],
435
- "expires_at": r[3],
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
- @mcp.tool(
442
- name="kv_search",
443
- description="Full-text search across keys and values using FTS5. "
444
- "Optionally filter by namespace.",
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
- Returns:
461
- List of dicts with namespace, key, value, created_at, score.
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 = _db(scope)
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
- @mcp.tool(
505
- name="purge_expired",
506
- description="Purge expired TTL entries. Optionally dry-run to see count "
507
- "without deleting. Logs purged keys to deletelog.",
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
- async def purge_expired(
510
- scope: str = "project",
511
- dry_run: bool = False,
512
- ) -> dict:
513
- """Purge expired TTL entries from the database.
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
- Args:
516
- scope: 'project' (default) or 'global'.
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
- Returns:
520
- Dict with purged count and dry_run flag.
521
- """
522
- conn = _db(scope)
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
- # Find expired entries first
525
- expired = conn.execute(
526
- "SELECT key FROM kv_store "
527
- "WHERE expires_at IS NOT NULL "
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
- if dry_run:
535
- return {"purged": count, "dry_run": True}
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
- # Mark as deleted (soft delete)
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
- # Write deletelog
550
- db_path = _resolve_db_path(scope)
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
- def _opportunistic_auto_purge(
558
- conn: sqlite3.Connection, namespace: str, threshold: int = 500
559
- ) -> None:
560
- """Lightweight auto-purge when a namespace exceeds its threshold."""
561
- count = conn.execute(
562
- "SELECT COUNT(*) FROM kv_store WHERE namespace = ? AND deleted_at IS NULL",
563
- (namespace,),
564
- ).fetchone()[0]
565
- if count <= threshold:
566
- return
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
- conn.execute(
569
- "UPDATE kv_store SET deleted_at = datetime('now') "
570
- "WHERE namespace = ? AND expires_at IS NOT NULL "
571
- "AND datetime(expires_at) < datetime('now') AND deleted_at IS NULL",
572
- (namespace,),
573
- )
574
- conn.commit()
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="kv_delete_namespace",
1289
+ name="goal_create",
579
1290
  description=(
580
- "Delete all entries in a namespace. Optionally limit to entries older "
581
- "than N days."
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 kv_delete_namespace(
585
- namespace: str,
586
- scope: str = "project",
587
- older_than_days: int | None = None,
588
- ) -> dict:
589
- """Delete all entries in a namespace, optionally old entries only.
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
- Returns:
597
- Dict with deleted count.
598
- """
599
- conn = _db(scope)
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
- if older_than_days is not None:
602
- cursor = conn.execute(
603
- "DELETE FROM kv_store WHERE namespace = ? "
604
- "AND datetime(created_at) < datetime('now', ? || ' days')",
605
- (namespace, f"-{older_than_days}"),
606
- )
607
- else:
608
- cursor = conn.execute(
609
- "DELETE FROM kv_store WHERE namespace = ?",
610
- (namespace,),
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
- conn.commit()
1376
+ except GoalStoreError as exc:
1377
+ raise _goal_tool_error(exc) from None
1378
+ return {"goal": _public_goal(record)}
613
1379
 
614
- return {"deleted": cursor.rowcount}
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
- # Session-scoped context storage for deepwork checkpoints, phase state,
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 _validate_bounded_text(value: object, field: str, limit: int) -> None:
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 (rehydrate does not consume it),
969
- not a persistence requirement. It may be a positive integer, a JSON float
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, (int, float)):
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
- # (field, validator, python type, wording) in report order. ``tail`` is the one
989
- # array section; the rest are objects. ``None`` sections are OPTIONAL and are
990
- # never reported — heartbeat checkpoints omit goal/phase by design.
991
- CHECKPOINT_SECTIONS: tuple[tuple[str, Callable[[object], object], type, str], ...] = (
992
- ("goal", _validate_goal, dict, "an object"),
993
- ("phase", _validate_phase, dict, "an object"),
994
- ("delegations", _validate_delegations, dict, "an object"),
995
- ("tail", _validate_tail, list, "an array"),
996
- ("heartbeat", _validate_heartbeat, dict, "an object"),
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 _validate_checkpoint_shape(checkpoint: dict) -> None:
1001
- """Validate bounded structured checkpoint fields without sanitizing them.
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
- Fail-fast on purpose: the read path needs only a yes/no verdict.
1004
- ``context_save`` uses ``_collect_checkpoint_errors`` so a single call
1005
- reports every invalid section instead of only the first.
1006
- """
1007
- _validate_version_metadata(checkpoint.get("version"))
1008
- for field, validator, _expected_type, _wording in CHECKPOINT_SECTIONS:
1009
- value = checkpoint.get(field)
1010
- if value is not None:
1011
- validator(value)
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
- for field, validator, expected_type, wording in CHECKPOINT_SECTIONS:
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
- validator(value)
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, but rehydrate never treats
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 JSON in persistence KV with a key-specific TTL. "
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 a context checkpoint with session-level isolation.
1978
+ """Save an operational-state checkpoint for the supplied session ID.
1232
1979
 
1233
- Namespace is always "checkpoint:{slug}:{session_id}", preventing
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 unique session ID for namespace isolation.
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 namespace, key, and session_id for subsequent calls.
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 a context checkpoint with session isolation.
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 unqualified legacy namespace when no
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__":