notepad.py 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166
  1. """Per-job durable KV notepad (cursors, watermarks) carried across cron wake-ups; profile-local
  2. SQLite next to the executions ledger (same connection/pragma pattern as ``cron/executions.py``).
  3. Caps are a documented contract: ``MAX_VALUE_BYTES`` (16 KB per value, UTF-8) and
  4. ``MAX_JOB_TOTAL_BYTES`` (64 KB per job, key+value). Oversized writes raise ``ValueError`` and leave
  5. the store untouched — the notepad is prompt-injected each run. Write path is the CLI
  6. (``hermes cron notepad <job_id> set ...``) via the terminal tool; no model tool is added.
  7. """
  8. from __future__ import annotations
  9. import sqlite3
  10. import threading
  11. from contextlib import contextmanager
  12. from pathlib import Path
  13. from typing import Any, Dict, Iterator, List, Optional
  14. from hermes_constants import get_hermes_home
  15. from hermes_time import now as _hermes_now
  16. # Optional test override. Production resolves the path at transaction time so multiplexed profile
  17. # ticks (set_hermes_home_override) cannot leak one profile's notepad rows into the import-time home
  18. # — and remove_job's clear_notepad cannot wipe the wrong profile's DB.
  19. # Same pattern as cron/executions.py. See #86519.
  20. NOTEPAD_FILE: Optional[Path] = None
  21. MAX_VALUE_BYTES = 16 * 1024
  22. MAX_KEY_CHARS = 128
  23. MAX_JOB_TOTAL_BYTES = 64 * 1024
  24. _lock = threading.RLock()
  25. def _current_notepad_file() -> Path:
  26. return NOTEPAD_FILE or (get_hermes_home().resolve() / "cron" / "notepad.db")
  27. def _connect() -> sqlite3.Connection:
  28. # Late imports: a scheduler daemon that outlives an on-disk upgrade already has the OLD
  29. # ``hermes_cli.sqlite_util`` / ``cron.jobs`` cached, so new names must be resolved at call time,
  30. # not at import time (the guarantee cron/ledger.py used to carry, see e24c8499).
  31. from cron.jobs import _ensure_cron_dir
  32. from hermes_cli.sqlite_util import open_db
  33. path = _current_notepad_file()
  34. _ensure_cron_dir(path.parent)
  35. return open_db(path, db_label="cron/notepad.db", initialize=_initialize_schema)
  36. def _initialize_schema(conn: sqlite3.Connection) -> None:
  37. conn.execute(
  38. """CREATE TABLE IF NOT EXISTS cron_notepad (
  39. job_id TEXT NOT NULL,
  40. key TEXT NOT NULL,
  41. value TEXT NOT NULL,
  42. updated_at TEXT NOT NULL,
  43. PRIMARY KEY (job_id, key)
  44. )"""
  45. )
  46. @contextmanager
  47. def _transaction() -> Iterator[sqlite3.Connection]:
  48. from hermes_cli.sqlite_util import transaction
  49. with _lock, transaction(_connect()) as conn:
  50. yield conn
  51. def _validate(job_id: str, key: str, value: str) -> None:
  52. if not str(job_id):
  53. raise ValueError("job_id must be non-empty")
  54. if not key:
  55. raise ValueError("key must be non-empty")
  56. if len(key) > MAX_KEY_CHARS:
  57. raise ValueError(f"key too long (max {MAX_KEY_CHARS} characters)")
  58. if len(value.encode("utf-8")) > MAX_VALUE_BYTES:
  59. raise ValueError(f"value too large (max {MAX_VALUE_BYTES} bytes per key)")
  60. def set_note(job_id: str, key: str, value: str) -> dict[str, Any]:
  61. """Upsert one key. Raises ValueError when a size cap would be exceeded."""
  62. job_id, key, value = str(job_id), str(key), str(value)
  63. _validate(job_id, key, value)
  64. now = _hermes_now().isoformat()
  65. with _transaction() as conn:
  66. row = conn.execute(
  67. """SELECT COALESCE(SUM(LENGTH(CAST(key AS BLOB))
  68. + LENGTH(CAST(value AS BLOB))), 0)
  69. FROM cron_notepad WHERE job_id=? AND key<>?""",
  70. (job_id, key),
  71. ).fetchone()
  72. other_bytes = int(row[0])
  73. entry_bytes = len(key.encode("utf-8")) + len(value.encode("utf-8"))
  74. if other_bytes + entry_bytes > MAX_JOB_TOTAL_BYTES:
  75. raise ValueError(
  76. f"notepad full: job '{job_id}' would exceed "
  77. f"{MAX_JOB_TOTAL_BYTES} bytes total; delete unused keys first"
  78. )
  79. conn.execute(
  80. """INSERT INTO cron_notepad (job_id, key, value, updated_at)
  81. VALUES (?, ?, ?, ?)
  82. ON CONFLICT(job_id, key)
  83. DO UPDATE SET value=excluded.value, updated_at=excluded.updated_at""",
  84. (job_id, key, value, now),
  85. )
  86. return {"job_id": job_id, "key": key, "value": value, "updated_at": now}
  87. def get_note(job_id: str, key: str) -> Optional[str]:
  88. with _transaction() as conn:
  89. row = conn.execute(
  90. "SELECT value FROM cron_notepad WHERE job_id=? AND key=?",
  91. (str(job_id), str(key)),
  92. ).fetchone()
  93. return None if row is None else row["value"]
  94. def delete_note(job_id: str, key: str) -> bool:
  95. with _transaction() as conn:
  96. cur = conn.execute(
  97. "DELETE FROM cron_notepad WHERE job_id=? AND key=?",
  98. (str(job_id), str(key)),
  99. )
  100. return cur.rowcount > 0
  101. def list_notes(job_id: str) -> list[dict[str, Any]]:
  102. """All entries for one job, sorted by key."""
  103. with _transaction() as conn:
  104. rows = conn.execute(
  105. "SELECT job_id, key, value, updated_at FROM cron_notepad "
  106. "WHERE job_id=? ORDER BY key",
  107. (str(job_id),),
  108. ).fetchall()
  109. return [dict(row) for row in rows]
  110. def clear_notepad(job_id: str) -> int:
  111. """Delete every key for one job (called from ``cron.jobs.remove_job``). Returns row count;
  112. no-ops without creating the DB when no notepad file exists yet."""
  113. if not _current_notepad_file().exists():
  114. return 0
  115. with _transaction() as conn:
  116. cur = conn.execute(
  117. "DELETE FROM cron_notepad WHERE job_id=?", (str(job_id),)
  118. )
  119. return cur.rowcount
  120. def render_notepad_section(job_id: str) -> str:
  121. """Render a job's notepad as a prompt section. An empty notepad MUST return '' so jobs that
  122. never use the feature get a byte-identical prompt (prompt-cache + drift safety)."""
  123. try:
  124. notes = list_notes(job_id)
  125. except Exception:
  126. return ""
  127. if not notes:
  128. return ""
  129. lines = [f"- {note['key']}: {note['value']}" for note in notes]
  130. return (
  131. "## Job notepad (persistent across runs)\n"
  132. "This durable scratchpad survives between scheduled runs of this "
  133. "job. Update it via the CLI, e.g.:\n"
  134. f"`hermes cron notepad {job_id} set <key> <value>` "
  135. f"(also: get/delete/list; `hermes cron notepad {job_id} delete "
  136. "<key>` removes an entry).\n\n" + "\n".join(lines) + "\n\n"
  137. )