hindsight-embed 1.2.1__tar.gz → 1.2.2__tar.gz

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 (66) hide show
  1. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/PKG-INFO +1 -1
  2. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/__init__.py +1 -1
  3. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/daemon_embed_manager.py +178 -6
  4. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/env.example +85 -2
  5. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/profile_manager.py +2 -0
  6. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/pyproject.toml +1 -1
  7. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/test_daemon_client.py +156 -1
  8. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/test_embed_manager.py +3 -1
  9. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/test_profile_daemon_config.py +2 -0
  10. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/.gitignore +0 -0
  11. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/LICENSE +0 -0
  12. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/README.md +0 -0
  13. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/_http_probe.py +0 -0
  14. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/cli.py +0 -0
  15. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/__init__.py +0 -0
  16. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/lifecycle.py +0 -0
  17. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/providers.py +0 -0
  18. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/server.py +0 -0
  19. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/service.py +0 -0
  20. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/assets/index-Bti1AEAP.css +0 -0
  21. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/assets/index-D7TwAsED.js +0 -0
  22. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/favicon.png +0 -0
  23. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/fonts/Inter-400.woff2 +0 -0
  24. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/fonts/Inter-500.woff2 +0 -0
  25. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/fonts/Inter-600.woff2 +0 -0
  26. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/fonts/JetBrainsMono-400.woff2 +0 -0
  27. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/fonts/JetBrainsMono-500.woff2 +0 -0
  28. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/fonts/SpaceGrotesk-500.woff2 +0 -0
  29. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/fonts/SpaceGrotesk-600.woff2 +0 -0
  30. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/fonts/SpaceGrotesk-700.woff2 +0 -0
  31. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/index.html +0 -0
  32. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/static/logo.png +0 -0
  33. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/README.md +0 -0
  34. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/index.html +0 -0
  35. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/package-lock.json +0 -0
  36. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/package.json +0 -0
  37. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/public/favicon.png +0 -0
  38. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/public/fonts/Inter-400.woff2 +0 -0
  39. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/public/fonts/Inter-500.woff2 +0 -0
  40. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/public/fonts/Inter-600.woff2 +0 -0
  41. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/public/fonts/JetBrainsMono-400.woff2 +0 -0
  42. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/public/fonts/JetBrainsMono-500.woff2 +0 -0
  43. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/public/fonts/SpaceGrotesk-500.woff2 +0 -0
  44. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/public/fonts/SpaceGrotesk-600.woff2 +0 -0
  45. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/public/fonts/SpaceGrotesk-700.woff2 +0 -0
  46. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/public/logo.png +0 -0
  47. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/src/api.js +0 -0
  48. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/src/app.jsx +0 -0
  49. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/src/main.jsx +0 -0
  50. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/src/service-panel.jsx +0 -0
  51. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/src/style.css +0 -0
  52. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/control_center/ui/vite.config.js +0 -0
  53. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/daemon_client.py +0 -0
  54. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/embed_manager.py +0 -0
  55. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/env_template.py +0 -0
  56. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/hindsight_embed/py.typed +0 -0
  57. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/test.sh +0 -0
  58. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/__init__.py +0 -0
  59. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/http_stub.py +0 -0
  60. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/test_cli_forwarding.py +0 -0
  61. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/test_control_center.py +0 -0
  62. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/test_env_template.py +0 -0
  63. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/test_http_probe.py +0 -0
  64. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/test_profile_integration.py +0 -0
  65. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/test_profile_lock.py +0 -0
  66. {hindsight_embed-1.2.1 → hindsight_embed-1.2.2}/tests/test_profile_manager.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: hindsight-embed
3
- Version: 1.2.1
3
+ Version: 1.2.2
4
4
  Summary: Hindsight embedded CLI - local memory operations without a server
5
5
  License-Expression: MIT
6
6
  License-File: LICENSE
@@ -3,7 +3,7 @@
3
3
  from .daemon_embed_manager import DaemonEmbedManager
4
4
  from .embed_manager import EmbedManager
5
5
 
6
- __version__ = "1.2.1"
6
+ __version__ = "1.2.2"
7
7
 
8
8
  __all__ = [
9
9
  "EmbedManager",
@@ -11,6 +11,8 @@ import os
11
11
  import platform
12
12
  import re
13
13
  import signal
14
+ import socket
15
+ import struct
14
16
  import subprocess
15
17
  import sys
16
18
  import sysconfig
@@ -28,7 +30,7 @@ from rich.text import Text
28
30
 
29
31
  from ._http_probe import ProbeResponse, probe_get
30
32
  from .embed_manager import EmbedManager
31
- from .profile_manager import ProfileLockTimeout, ProfileManager, lock_file, unlock_file
33
+ from .profile_manager import ProfileLockTimeout, ProfileManager, ProfilePaths, lock_file, unlock_file
32
34
 
33
35
  logger = logging.getLogger(__name__)
34
36
  console = Console(stderr=True)
@@ -71,6 +73,13 @@ def _parse_non_negative_int(value: str | None, default: int, name: str) -> int:
71
73
  # runners than POSIX.
72
74
  DAEMON_STARTUP_TIMEOUT = int(os.getenv("HINDSIGHT_EMBED_DAEMON_STARTUP_TIMEOUT", "180"))
73
75
  DAEMON_STARTUP_TERMINATE_TIMEOUT = 10
76
+ # How long a start waits for the daemon it replaces to finish exiting. A stopping
77
+ # daemon frees its port first, then drains in-flight work (up to
78
+ # HINDSIGHT_API_WORKER_SHUTDOWN_DRAIN_SECONDS, 20s by default), and only then stops
79
+ # the profile's embedded Postgres. A replacement started inside that window ran its
80
+ # migrations against a Postgres the old daemon then shut down: "Database migration
81
+ # failed" on restart (#6540). Generous on purpose: waiting is cheap, the race is not.
82
+ PREVIOUS_DAEMON_EXIT_TIMEOUT = 60.0
74
83
  DEFAULT_DAEMON_IDLE_TIMEOUT = 0 # 0 = disabled (no auto-exit)
75
84
  ENV_DAEMON_LOG_MAX_BYTES = "HINDSIGHT_EMBED_DAEMON_LOG_MAX_BYTES"
76
85
  ENV_DAEMON_LOG_BACKUP_COUNT = "HINDSIGHT_EMBED_DAEMON_LOG_BACKUP_COUNT"
@@ -186,6 +195,39 @@ def _strip_parent_interpreter_env(env: dict[str, str]) -> dict[str, str]:
186
195
  return {key: value for key, value in env.items() if key not in _PARENT_INTERPRETER_ENV}
187
196
 
188
197
 
198
+ _AF_INET = 2
199
+ _AF_INET6 = 23
200
+ _ERROR_INSUFFICIENT_BUFFER = 122
201
+
202
+
203
+ @dataclass(frozen=True)
204
+ class _TcpRowLayout:
205
+ """Where the fields sit in one GetExtendedTcpTable row (TCP_TABLE_OWNER_PID_*)."""
206
+
207
+ size: int
208
+ port_offset: int
209
+ pid_offset: int
210
+
211
+
212
+ # MIB_TCPROW_OWNER_PID is six DWORDs; MIB_TCP6ROW_OWNER_PID puts a 16-byte address
213
+ # and a scope id before the port.
214
+ _TCP_ROW_LAYOUT = {_AF_INET: _TcpRowLayout(24, 8, 20), _AF_INET6: _TcpRowLayout(56, 20, 52)}
215
+
216
+
217
+ def _listener_pids_from_tcp_table(table: bytes, family: int, port: int) -> list[int]:
218
+ """Owning PIDs of the rows bound to `port` in a raw GetExtendedTcpTable buffer."""
219
+ layout = _TCP_ROW_LAYOUT[family]
220
+ (count,) = struct.unpack_from("<I", table, 0)
221
+ pids: list[int] = []
222
+ for index in range(count):
223
+ row = 4 + index * layout.size
224
+ (raw_port,) = struct.unpack_from("<I", table, row + layout.port_offset)
225
+ # The port sits in network byte order in the DWORD's low 16 bits.
226
+ if socket.ntohs(raw_port & 0xFFFF) == port:
227
+ pids.append(struct.unpack_from("<I", table, row + layout.pid_offset)[0])
228
+ return pids
229
+
230
+
189
231
  def _detach_popen_kwargs(log_handle: IO[bytes]) -> dict:
190
232
  """Cross-platform kwargs to spawn a subprocess detached from the caller.
191
233
 
@@ -239,6 +281,25 @@ def _signal_startup_process(process: subprocess.Popen, *, force: bool) -> None:
239
281
  os.killpg(process.pid, signal.SIGKILL if force else signal.SIGTERM)
240
282
 
241
283
 
284
+ def _kill_process_tree(pid: int) -> None:
285
+ """Force-kill a daemon we launched and everything it started.
286
+
287
+ Like `_signal_startup_process`: the pid may be the ``uvx`` launcher, and
288
+ killing only it would leave the real API holding the embedded Postgres.
289
+ """
290
+ if platform.system() == "Windows":
291
+ DaemonEmbedManager._run_probe(["taskkill", "/T", "/F", "/PID", str(pid)])
292
+ return
293
+ try:
294
+ os.killpg(pid, signal.SIGKILL)
295
+ except OSError:
296
+ # Not a group leader after all: kill what there is.
297
+ try:
298
+ os.kill(pid, signal.SIGKILL)
299
+ except OSError:
300
+ pass
301
+
302
+
242
303
  def _terminate_startup_process(process: subprocess.Popen) -> None:
243
304
  """Stop the daemon child owned by a failed startup attempt, escalating to kill."""
244
305
  if process.poll() is not None:
@@ -584,8 +645,8 @@ class DaemonEmbedManager(EmbedManager):
584
645
  host that has plenty.
585
646
 
586
647
  `errors="replace"` is the half that makes it deterministic; `encoding` alone
587
- still raises. Only the localized header carries non-ASCII, so every line the
588
- parsers read survives intact and neither needed changing.
648
+ still raises. A replaced character can land in the netstat state column too
649
+ ("ABHÖREN"), which is why `_windows_listening_pids` does not read that column.
589
650
  """
590
651
  try:
591
652
  result = subprocess.run(
@@ -603,15 +664,25 @@ class DaemonEmbedManager(EmbedManager):
603
664
 
604
665
  @staticmethod
605
666
  def _windows_listening_pids(port: int) -> list[int]:
606
- """PIDs listening on `port` according to netstat."""
667
+ """PIDs listening on `port`: asked from the kernel, netstat only as a fallback.
668
+
669
+ netstat prints its state column in the display language ("ABHÖREN" on a
670
+ German Windows) and is a subprocess that a loaded machine can push past the
671
+ probe deadline. Either way the caller got no PID for a daemon that was up,
672
+ and `daemon stop` / the stale-daemon restart refused to act (#6602).
673
+ """
674
+ native = DaemonEmbedManager._windows_native_listening_pids(port)
675
+ if native is not None:
676
+ return native
607
677
  output = DaemonEmbedManager._run_probe(["netstat", "-ano", "-p", "TCP"])
608
678
  if output is None:
609
679
  return []
610
680
  pids: list[int] = []
611
681
  for line in output.splitlines():
612
682
  fields = line.split()
613
- # proto, local address, foreign address, state, pid
614
- if len(fields) < 5 or fields[-2] != "LISTENING":
683
+ # proto, local address, foreign address, state, pid. The state is
684
+ # localized ("ABHÖREN"), so a listener is told by its foreign port 0.
685
+ if len(fields) < 5 or fields[0] != "TCP" or not fields[2].endswith(":0"):
615
686
  continue
616
687
  # Match on the local address' port only: the daemon binds 127.0.0.1
617
688
  # but the UI can bind 0.0.0.0 or [::1] (issue #3527), and an
@@ -625,6 +696,48 @@ class DaemonEmbedManager(EmbedManager):
625
696
  continue
626
697
  return pids
627
698
 
699
+ @staticmethod
700
+ def _windows_native_listening_pids(port: int) -> list[int] | None:
701
+ """PIDs listening on `port` from GetExtendedTcpTable, or None if it can't be read.
702
+
703
+ The table carries the state as a number and the owning PID, so nothing here
704
+ depends on the display language, and it answers without a subprocess.
705
+ """
706
+ import ctypes
707
+ from ctypes import wintypes
708
+
709
+ win_dll = getattr(ctypes, "WinDLL", None) # only defined on Windows
710
+ if win_dll is None:
711
+ return None
712
+ try:
713
+ get_table = win_dll("iphlpapi").GetExtendedTcpTable
714
+ except (OSError, AttributeError):
715
+ return None
716
+ get_table.restype = wintypes.DWORD
717
+ get_table.argtypes = [
718
+ ctypes.c_void_p,
719
+ ctypes.POINTER(wintypes.DWORD),
720
+ wintypes.BOOL,
721
+ wintypes.ULONG,
722
+ ctypes.c_int, # TCP_TABLE_CLASS
723
+ wintypes.ULONG,
724
+ ]
725
+ tcp_table_owner_pid_listener = 3
726
+ pids: list[int] = []
727
+ for family in (_AF_INET, _AF_INET6):
728
+ size = wintypes.DWORD(0)
729
+ # The first call only reports the size the table needs. The table can
730
+ # grow between the two calls, so retry while it says the buffer is short.
731
+ for _attempt in range(3):
732
+ buffer = ctypes.create_string_buffer(max(size.value, 4))
733
+ status = get_table(buffer, ctypes.byref(size), False, family, tcp_table_owner_pid_listener, 0)
734
+ if status != _ERROR_INSUFFICIENT_BUFFER:
735
+ break
736
+ if status != 0:
737
+ return None
738
+ pids.extend(_listener_pids_from_tcp_table(buffer.raw, family, port))
739
+ return pids
740
+
628
741
  @staticmethod
629
742
  def _posix_listening_pids(port: int) -> list[int]:
630
743
  """PIDs listening on `port`, via lsof, falling back to ss.
@@ -819,6 +932,57 @@ class DaemonEmbedManager(EmbedManager):
819
932
  return True # Already gone
820
933
  return False
821
934
 
935
+ @staticmethod
936
+ def _daemon_pid_file(paths: ProfilePaths) -> Path:
937
+ """Where the start path records the PID of the daemon it launched."""
938
+ return paths.log.with_suffix(".pid")
939
+
940
+ @staticmethod
941
+ def _is_profile_daemon(pid: int, port: int) -> bool:
942
+ """True while `pid` is alive and is the daemon launched for `port`.
943
+
944
+ The port check guards against PID reuse (another profile's daemon, or
945
+ anything else) and rules out an exited daemon left as a zombie, whose
946
+ command line no longer carries its arguments.
947
+ """
948
+ cmdline = DaemonEmbedManager._process_command_line(pid)
949
+ if cmdline is None:
950
+ return False
951
+ lowered = cmdline.lower()
952
+ return any(marker in lowered for marker in DAEMON_PROCESS_MARKERS) and (
953
+ re.search(rf"--port[ =]{port}(\s|$)", lowered) is not None
954
+ )
955
+
956
+ def _wait_for_previous_daemon_exit(self, paths: ProfilePaths) -> None:
957
+ """Block until the daemon this profile last launched has exited.
958
+
959
+ Callers reach this with the port already free, so a recorded daemon that
960
+ is still alive is one that is shutting down and has yet to stop the
961
+ embedded Postgres a replacement would share. If it outlives the wait it
962
+ is hung; it is killed so the start can proceed.
963
+ """
964
+ pid_file = self._daemon_pid_file(paths)
965
+ try:
966
+ pid = int(pid_file.read_text().strip())
967
+ except (OSError, ValueError):
968
+ return
969
+
970
+ def _exited_within(seconds: float) -> bool:
971
+ deadline = time.monotonic() + seconds
972
+ while self._is_profile_daemon(pid, paths.port):
973
+ if time.monotonic() >= deadline:
974
+ return False
975
+ time.sleep(0.2)
976
+ return True
977
+
978
+ if self._is_profile_daemon(pid, paths.port):
979
+ logger.info(f"Waiting for the previous daemon (PID {pid}) to finish shutting down")
980
+ if not _exited_within(PREVIOUS_DAEMON_EXIT_TIMEOUT):
981
+ logger.warning(f"Previous daemon (PID {pid}) did not exit in time; killing it")
982
+ _kill_process_tree(pid)
983
+ _exited_within(DAEMON_STARTUP_TERMINATE_TIMEOUT)
984
+ pid_file.unlink(missing_ok=True)
985
+
822
986
  @staticmethod
823
987
  def _port_health_ok(port: int) -> bool:
824
988
  """Return True when the listener on port responds like initialized Hindsight."""
@@ -964,6 +1128,10 @@ class DaemonEmbedManager(EmbedManager):
964
1128
  self._register_profile(profile, port, config)
965
1129
  return True
966
1130
 
1131
+ # A free port does not mean the previous daemon is gone (see
1132
+ # PREVIOUS_DAEMON_EXIT_TIMEOUT).
1133
+ self._wait_for_previous_daemon_exit(paths)
1134
+
967
1135
  # Load profile's .env file and merge with provided config
968
1136
  # This fixes issue #305 where profile env vars were ignored
969
1137
  profile_config = self._profile_manager.load_profile_config(profile)
@@ -1053,6 +1221,10 @@ class DaemonEmbedManager(EmbedManager):
1053
1221
  # can close its handle as soon as Popen returns.
1054
1222
  with open(daemon_log, "ab") as daemon_log_handle:
1055
1223
  daemon_process = subprocess.Popen(cmd, env=env, **_detach_popen_kwargs(daemon_log_handle))
1224
+ try:
1225
+ self._daemon_pid_file(paths).write_text(str(daemon_process.pid))
1226
+ except OSError:
1227
+ logger.debug("Could not record daemon PID for %s", profile_label, exc_info=True)
1056
1228
 
1057
1229
  # Wait for daemon to be ready with rich UI
1058
1230
  start_time = time.time()
@@ -68,6 +68,12 @@ HINDSIGHT_API_LLM_MODEL=gpt-4o-mini
68
68
  # pointed at a local server that can't constrain output: the schema then goes in
69
69
  # the prompt only.
70
70
  # HINDSIGHT_API_LLM_OPENAI_COMPATIBLE_JSON_MODE=
71
+ # On that path, have the backend enforce the response schema itself instead of
72
+ # json_object (any JSON object). For vLLM / llama.cpp; set true for Gemma 4 on vLLM.
73
+ # HINDSIGHT_API_LLM_OPENAI_COMPATIBLE_ENFORCE_SCHEMA=false
74
+ # JSON_MODE for retain's fact extraction only (unset = the global value). Set false
75
+ # for Gemma 4 on vLLM: constrained, it answers retain with an empty facts list.
76
+ # HINDSIGHT_API_RETAIN_LLM_OPENAI_COMPATIBLE_JSON_MODE=
71
77
 
72
78
  # Constrain retain's occurred_start/occurred_end to an ISO timestamp with a JSON
73
79
  # Schema pattern. Stops grammar-constrained models reasoning inside the timestamp
@@ -105,6 +111,9 @@ HINDSIGHT_API_LLM_MODEL=gpt-4o-mini
105
111
  # outright -- e.g. Bedrock Claude in ap-southeast-2 ("Extra inputs are not permitted");
106
112
  # the same model in us-east-1 accepts response_format and needs nothing here.
107
113
  # HINDSIGHT_API_LLM_STRUCTURED_OUTPUT_IN_PROMPT=false
114
+ # LiteLLM/Bedrock: mark the prompt for the provider's prompt cache. Unset = on for models
115
+ # named "claude"; set true for a Claude model behind an ARN or alias, false to turn it off.
116
+ # HINDSIGHT_API_LLM_LITELLM_PROMPT_CACHE=
108
117
 
109
118
  # Transport-level output cap for reflect's final synthesis call. Unset = uncapped:
110
119
  # the model runs to a natural stop and the reflect/mental-model max_tokens governs
@@ -154,7 +163,7 @@ HINDSIGHT_API_LLM_MODEL=gpt-4o-mini
154
163
  # Example: z.ai configuration (Zhipu GLM series, https://z.ai)
155
164
  # HINDSIGHT_API_LLM_PROVIDER=zai
156
165
  # HINDSIGHT_API_LLM_API_KEY=your-zai-api-key
157
- # HINDSIGHT_API_LLM_MODEL=glm-4.5-flash # or glm-4.5-air for the paid tier
166
+ # HINDSIGHT_API_LLM_MODEL=glm-5.3-flash # or glm-4.5-flash for the free tier
158
167
 
159
168
  # Example: Atlas Cloud configuration (OpenAI-compatible, https://www.atlascloud.ai)
160
169
  # HINDSIGHT_API_LLM_PROVIDER=atlas
@@ -573,6 +582,17 @@ HINDSIGHT_API_LOG_LEVEL=info
573
582
  # HINDSIGHT_API_MENTAL_MODEL_DELTA_USE_DECISION_MODEL=true
574
583
  # Above this many new memories a delta refresh searches instead of asking the decision model about each (server-level)
575
584
  # HINDSIGHT_API_MENTAL_MODEL_DELTA_GATE_MAX_MEMORIES=200
585
+ # How an interactive reflect searches the knowledge banks a memory bank links.
586
+ # Media types the search may return (comma-separated: document,image,audio,video,text; unset = all; per bank)
587
+ # HINDSIGHT_API_REFLECT_KB_SEARCH_MEDIA_TYPES=
588
+ # Show the model the picture behind an image or PDF-page hit, when it is known to read images (server-level)
589
+ # HINDSIGHT_API_REFLECT_KB_SEARCH_IMAGES=true
590
+ # The most pictures one search hands the model (0 = none; server-level)
591
+ # HINDSIGHT_API_REFLECT_KB_SEARCH_MAX_IMAGES=4
592
+ # How deep the search ranks before its token budget picks: low, mid or high (server-level)
593
+ # HINDSIGHT_API_REFLECT_KB_SEARCH_BUDGET=mid
594
+ # Filter the search by the reflect's tags/tags_match/tag_groups, as its memories are (per bank)
595
+ # HINDSIGHT_API_REFLECT_KB_SEARCH_APPLY_TAGS=true
576
596
 
577
597
  # Admission control. The *_MAX_CONCURRENT caps above bound how much runs at once and
578
598
  # let an unbounded queue form behind them; these bound how long a request may WAIT
@@ -711,8 +731,11 @@ HINDSIGHT_API_LOG_LEVEL=info
711
731
  # Not needed for hindsight on Hindsight Inference, which fits each request itself (no token split);
712
732
  # hindsight on a custom BASE_URL (your own vLLM) splits at 54000:
713
733
  # HINDSIGHT_API_DECISION_MODEL_MAX_REQUEST_TOKENS=26000
734
+ # Show the decision model pictures (reflect's knowledge-bank pictures when it asks "is this enough?").
735
+ # System One providers only, on a model that reads images (Jev 1.13+); a preview, so off by default:
736
+ # HINDSIGHT_API_DECISION_MODEL_VISION=false
714
737
  # The vocabulary that ceiling and recall's caps are counted in: the served model's own (jev for typesafe, else
715
- # HINDSIGHT_API_TOKENIZER_ENCODING). Set it when the endpoint serves another model, e.g. qwen3.5:
738
+ # HINDSIGHT_API_TOKENIZER_ENCODING). Set it when the endpoint serves another model, e.g. qwen3.5 or hs-decide-1-flash:
716
739
  # HINDSIGHT_API_DECISION_MODEL_TOKENIZER=jev
717
740
  # Recall: when it has a decision model, it replaces the reranker above. Each candidate is
718
741
  # judged on whether it helps answer the question, told the question's date (else today),
@@ -784,6 +807,66 @@ HINDSIGHT_API_LOG_LEVEL=info
784
807
  # HINDSIGHT_API_LLM_TRACE_MAX_CHARS=50000 # truncate stored input/output
785
808
  # HINDSIGHT_API_LLM_TRACE_DELETE_WITH_DOCUMENT=true # deleting a document deletes its trace rows (default: false)
786
809
 
810
+ # -----------------------------------------------------------------------------
811
+ # Knowledge banks (Optional; off by default while the feature is built)
812
+ # -----------------------------------------------------------------------------
813
+
814
+ # Turn knowledge banks on (documents a memory bank links, read by reflect)
815
+ # HINDSIGHT_API_ENABLE_KB=false
816
+ # The one embedder for every knowledge bank: local, gemini, vertex, voyage, cohere, openai or text
817
+ # HINDSIGHT_API_KB_EMBEDDINGS_PROVIDER=local
818
+ # Model (unset: the provider's own), key, and /v1 URL (openai: required)
819
+ # HINDSIGHT_API_KB_EMBEDDINGS_MODEL=
820
+ # HINDSIGHT_API_KB_EMBEDDINGS_API_KEY=
821
+ # HINDSIGHT_API_KB_EMBEDDINGS_BASE_URL=
822
+ # Vector size for a model that can shorten them (unset: the model's own)
823
+ # HINDSIGHT_API_KB_EMBEDDINGS_DIMENSIONS=
824
+ # openai provider: what the remote model embeds
825
+ # HINDSIGHT_API_KB_EMBEDDINGS_MODALITIES=text,image
826
+ # local provider: torch device (cpu, cuda, mps; unset picks one)
827
+ # HINDSIGHT_API_KB_EMBEDDINGS_DEVICE=
828
+ # Passages per embedder request, and remote requests in flight per process (0 = no cap)
829
+ # HINDSIGHT_API_KB_EMBEDDINGS_BATCH_SIZE=32
830
+ # HINDSIGHT_API_KB_EMBEDDINGS_MAX_IN_FLIGHT=16
831
+ # text provider: its own embeddings setup, any HINDSIGHT_API_EMBEDDINGS_* with this prefix
832
+ # HINDSIGHT_API_KB_TEXT_EMBEDDINGS_PROVIDER=
833
+ # Knowledge-bank search's reranker: any Cohere-style /rerank endpoint (full URL; unset: no rerank).
834
+ # The best hits go in one request, as many as MAX_TOKENS holds (a low search budget: at most 26000),
835
+ # counted with TOKENIZER (unset: HINDSIGHT_API_TOKENIZER_ENCODING); videos keep their search place.
836
+ # IMAGES sends image and PDF page hits as pictures with their text (false: a text-only reranker).
837
+ # MAX_TOKENS is sized for a long-window reranker: lower it to your reranker's window.
838
+ # HINDSIGHT_API_KB_RERANKER_URL=
839
+ # HINDSIGHT_API_KB_RERANKER_MODEL=
840
+ # HINDSIGHT_API_KB_RERANKER_API_KEY=
841
+ # HINDSIGHT_API_KB_RERANKER_MAX_TOKENS=120000
842
+ # HINDSIGHT_API_KB_RERANKER_TOKENIZER=
843
+ # HINDSIGHT_API_KB_RERANKER_IMAGES=true
844
+ # HINDSIGHT_API_KB_RERANKER_QUERY_IMAGES=false
845
+ # Ingest limits (the per-bank ones can be narrowed per knowledge bank)
846
+ # HINDSIGHT_API_KB_DISABLED_MEDIA_TYPES=
847
+ # HINDSIGHT_API_KB_MAX_FILE_MB=500
848
+ # HINDSIGHT_API_KB_MAX_MEDIA_SECONDS=7200
849
+ # HINDSIGHT_API_KB_MAX_PDF_PAGES=2000
850
+ # How files are split into passages (per bank)
851
+ # HINDSIGHT_API_KB_TEXT_PASSAGE_TOKENS=256
852
+ # HINDSIGHT_API_KB_IMAGE_TOKENS=280
853
+ # HINDSIGHT_API_KB_PDF_PAGE_PIXELS=1536
854
+ # HINDSIGHT_API_KB_PDF_BANDS=false
855
+ # HINDSIGHT_API_KB_AUDIO_WINDOW_SECONDS=60
856
+ # HINDSIGHT_API_KB_VIDEO_WINDOW_SECONDS=30
857
+ # HINDSIGHT_API_KB_MEDIA_OVERLAP_SECONDS=5
858
+ # Search weights: PDF text vs page image, and keyword matches
859
+ # HINDSIGHT_API_KB_PDF_TEXT_WEIGHT=0.7
860
+ # HINDSIGHT_API_KB_KEYWORD_WEIGHT=0.2
861
+ # Async ingest: worker task size in bytes, and memory one batch may hold (0 = off)
862
+ # HINDSIGHT_API_KB_INGEST_CHILD_BYTES=1048576
863
+ # HINDSIGHT_API_KB_INGEST_MEMORY_BUDGET_MB=128
864
+ # Named ingest strategies (JSON) and the default one
865
+ # HINDSIGHT_API_KB_INGEST_STRATEGIES=
866
+ # HINDSIGHT_API_KB_INGEST_DEFAULT_STRATEGY=
867
+ # Where documents and passages live (module.path:ClassName; unset: PostgreSQL)
868
+ # HINDSIGHT_API_KB_STORE_EXTENSION=
869
+
787
870
  # -----------------------------------------------------------------------------
788
871
  # Operations (Optional)
789
872
  # -----------------------------------------------------------------------------
@@ -487,6 +487,8 @@ class ProfileManager:
487
487
  stale_log.unlink(missing_ok=True)
488
488
  except OSError as exc:
489
489
  logger.warning("Could not remove log %s while deleting profile '%s': %s", stale_log, name, exc)
490
+ # The PID the start path recorded for the profile's daemon.
491
+ log_path.with_suffix(".pid").unlink(missing_ok=True)
490
492
 
491
493
  # Update metadata
492
494
  metadata = self._load_metadata()
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "hindsight-embed"
7
- version = "1.2.1"
7
+ version = "1.2.2"
8
8
  description = "Hindsight embedded CLI - local memory operations without a server"
9
9
  license = "MIT"
10
10
  readme = "README.md"
@@ -1,6 +1,8 @@
1
1
  """Tests for daemon_client module."""
2
2
 
3
+ import os
3
4
  import sys
5
+ import time
4
6
  from unittest.mock import MagicMock, Mock, patch
5
7
 
6
8
  import pytest
@@ -401,6 +403,9 @@ class TestStartDaemonSerialization:
401
403
 
402
404
  with (
403
405
  patch.object(DaemonEmbedManager, "_clear_port", side_effect=lambda _: calls.append("clear") or True),
406
+ patch.object(
407
+ DaemonEmbedManager, "_wait_for_previous_daemon_exit", side_effect=lambda _: calls.append("wait")
408
+ ),
404
409
  patch.object(DaemonEmbedManager, "is_running", side_effect=[False, True, True]),
405
410
  patch.object(
406
411
  DaemonEmbedManager, "_rotate_daemon_log", side_effect=lambda *_args, **_kwargs: calls.append("rotate")
@@ -416,7 +421,106 @@ class TestStartDaemonSerialization:
416
421
  ):
417
422
  assert manager._start_daemon_locked({}, "codex", paths) is True
418
423
 
419
- assert calls == ["clear", "rotate", "spawn"]
424
+ assert calls == ["clear", "wait", "rotate", "spawn"]
425
+
426
+ def test_start_waits_for_the_previous_daemon_to_exit(self, tmp_path):
427
+ """A free port is not a stopped daemon (#6540).
428
+
429
+ A stopping daemon frees its port first and stops the profile's embedded
430
+ Postgres last. A replacement spawned in between ran its migrations against
431
+ a Postgres that then went away. The stand-in below is "still shutting down"
432
+ for a moment after the port is free; the wait must outlast it.
433
+ """
434
+ import subprocess
435
+
436
+ from hindsight_embed.profile_manager import ProfilePaths
437
+
438
+ paths = ProfilePaths(
439
+ config=tmp_path / "embed", lock=tmp_path / "daemon.lock", log=tmp_path / "daemon.log", port=9600
440
+ )
441
+ exiting = subprocess.Popen(
442
+ [sys.executable, "-c", "import time; time.sleep(1.5)", "hindsight-api", "--port", "9600"]
443
+ )
444
+ try:
445
+ DaemonEmbedManager._daemon_pid_file(paths).write_text(str(exiting.pid))
446
+ DaemonEmbedManager()._wait_for_previous_daemon_exit(paths)
447
+ # The process is our child, so it lingered as a zombie until this
448
+ # poll() reaped it; the wait must have read that zombie as gone.
449
+ assert exiting.poll() is not None, "the wait returned while the previous daemon was alive"
450
+ assert not DaemonEmbedManager._daemon_pid_file(paths).exists()
451
+ finally:
452
+ exiting.kill()
453
+ exiting.wait()
454
+
455
+ def test_previous_daemon_pid_reused_by_another_process_is_ignored(self, tmp_path, monkeypatch):
456
+ """The recorded PID only counts while it is still a daemon on this profile's port."""
457
+ from hindsight_embed.profile_manager import ProfilePaths
458
+
459
+ paths = ProfilePaths(
460
+ config=tmp_path / "embed", lock=tmp_path / "daemon.lock", log=tmp_path / "daemon.log", port=9600
461
+ )
462
+ DaemonEmbedManager._daemon_pid_file(paths).write_text("4321")
463
+ monkeypatch.setattr(
464
+ DaemonEmbedManager,
465
+ "_process_command_line",
466
+ # 96000 starts with 9600: a prefix match would take it for ours.
467
+ staticmethod(lambda _pid: "python -m hindsight_api.main --idle-timeout 0 --port 96000"),
468
+ )
469
+ killed: list[int] = []
470
+ monkeypatch.setattr("hindsight_embed.daemon_embed_manager._kill_process_tree", killed.append)
471
+
472
+ DaemonEmbedManager()._wait_for_previous_daemon_exit(paths)
473
+
474
+ assert killed == []
475
+
476
+ @pytest.mark.skipif(sys.platform == "win32", reason="POSIX process groups")
477
+ def test_a_hung_previous_daemon_is_killed_with_what_it_started(self, tmp_path, monkeypatch):
478
+ """Past the wait, the kill reaches the whole group: the recorded PID may be
479
+ the uvx launcher, and the real API under it holds the embedded Postgres."""
480
+ import subprocess
481
+
482
+ from hindsight_embed.profile_manager import ProfilePaths
483
+
484
+ monkeypatch.setattr("hindsight_embed.daemon_embed_manager.PREVIOUS_DAEMON_EXIT_TIMEOUT", 0.2)
485
+ paths = ProfilePaths(
486
+ config=tmp_path / "embed", lock=tmp_path / "daemon.lock", log=tmp_path / "daemon.log", port=9600
487
+ )
488
+ grandchild_pid_file = tmp_path / "grandchild.pid"
489
+ launcher = subprocess.Popen(
490
+ [
491
+ sys.executable,
492
+ "-c",
493
+ "import subprocess, sys, time; "
494
+ "p = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(60)']); "
495
+ f"open({str(grandchild_pid_file)!r}, 'w').write(str(p.pid)); time.sleep(60)",
496
+ "hindsight-api",
497
+ "--port",
498
+ "9600",
499
+ ],
500
+ start_new_session=True,
501
+ )
502
+ try:
503
+ deadline = time.monotonic() + 10
504
+ while not grandchild_pid_file.exists() or not grandchild_pid_file.read_text():
505
+ assert time.monotonic() < deadline, "launcher never started its child"
506
+ time.sleep(0.05)
507
+ grandchild = int(grandchild_pid_file.read_text())
508
+ DaemonEmbedManager._daemon_pid_file(paths).write_text(str(launcher.pid))
509
+
510
+ DaemonEmbedManager()._wait_for_previous_daemon_exit(paths)
511
+
512
+ assert launcher.wait(timeout=5) is not None
513
+ deadline = time.monotonic() + 5
514
+ while True:
515
+ try:
516
+ os.kill(grandchild, 0)
517
+ except OSError:
518
+ break
519
+ assert time.monotonic() < deadline, "the process the launcher started survived the kill"
520
+ time.sleep(0.05)
521
+ finally:
522
+ launcher.kill()
523
+ launcher.wait()
420
524
 
421
525
 
422
526
  class TestDaemonLogRotation:
@@ -656,6 +760,7 @@ class TestListeningPidDiscovery:
656
760
  " TCP 127.0.0.1:29177 0.0.0.0:0 LISTENING 9999\n"
657
761
  )
658
762
  monkeypatch.setattr("hindsight_embed.daemon_embed_manager.platform.system", lambda: "Windows")
763
+ _force_netstat(monkeypatch)
659
764
  monkeypatch.setattr(
660
765
  "hindsight_embed.daemon_embed_manager.subprocess.run",
661
766
  lambda cmd, **kwargs: Mock(returncode=0, stdout=netstat),
@@ -663,6 +768,51 @@ class TestListeningPidDiscovery:
663
768
 
664
769
  assert DaemonEmbedManager._listening_pids(19177) == [4321, 4322]
665
770
 
771
+ def test_windows_netstat_in_another_language_still_finds_the_listener(self, monkeypatch):
772
+ """A German netstat says ABHÖREN, not LISTENING; the listener must still be found (#6602)."""
773
+ netstat = (
774
+ " TCP 127.0.0.1:9177 0.0.0.0:0 ABHÖREN 4321\n"
775
+ " TCP 127.0.0.1:9177 127.0.0.1:50000 HERGESTELLT 7777\n"
776
+ )
777
+ monkeypatch.setattr("hindsight_embed.daemon_embed_manager.platform.system", lambda: "Windows")
778
+ _force_netstat(monkeypatch)
779
+ monkeypatch.setattr(
780
+ "hindsight_embed.daemon_embed_manager.subprocess.run",
781
+ lambda cmd, **kwargs: Mock(returncode=0, stdout=netstat),
782
+ )
783
+
784
+ assert DaemonEmbedManager._listening_pids(9177) == [4321]
785
+
786
+ def test_reads_listener_pids_from_a_kernel_tcp_table(self):
787
+ """The GetExtendedTcpTable rows are decoded at the right offsets, for both families."""
788
+ import socket
789
+ import struct
790
+
791
+ from hindsight_embed.daemon_embed_manager import _AF_INET, _AF_INET6, _listener_pids_from_tcp_table
792
+
793
+ def v4_row(port: int, pid: int) -> bytes:
794
+ return struct.pack("<6I", 2, 0x0100007F, socket.htons(port), 0, 0, pid)
795
+
796
+ def v6_row(port: int, pid: int) -> bytes:
797
+ return bytes(16) + struct.pack("<2I", 0, socket.htons(port)) + bytes(16) + struct.pack("<4I", 0, 0, 2, pid)
798
+
799
+ v4 = struct.pack("<I", 2) + v4_row(9177, 4321) + v4_row(8888, 9999)
800
+ v6 = struct.pack("<I", 2) + v6_row(8888, 9999) + v6_row(9177, 4322)
801
+
802
+ assert _listener_pids_from_tcp_table(v4, _AF_INET, 9177) == [4321]
803
+ assert _listener_pids_from_tcp_table(v6, _AF_INET6, 9177) == [4322]
804
+ assert _listener_pids_from_tcp_table(struct.pack("<I", 0), _AF_INET, 9177) == []
805
+
806
+ @pytest.mark.skipif(sys.platform != "win32", reason="reads the Windows kernel")
807
+ def test_windows_native_lookup_finds_a_live_listener(self):
808
+ import socket
809
+
810
+ with socket.socket() as server:
811
+ server.bind(("127.0.0.1", 0))
812
+ server.listen()
813
+ port = server.getsockname()[1]
814
+ assert DaemonEmbedManager._windows_native_listening_pids(port) == [os.getpid()]
815
+
666
816
 
667
817
  class TestProcessOwnership:
668
818
  """Regression coverage for #3520: never signal a process we cannot identify."""
@@ -742,6 +892,11 @@ class TestProcessOwnership:
742
892
  assert DaemonEmbedManager._process_matches(1, DAEMON_PROCESS_MARKERS) is True
743
893
 
744
894
 
895
+ def _force_netstat(monkeypatch: pytest.MonkeyPatch) -> None:
896
+ """Send the Windows lookup to its netstat fallback. A real Windows runner would ask the kernel."""
897
+ monkeypatch.setattr(DaemonEmbedManager, "_windows_native_listening_pids", staticmethod(lambda _port: None))
898
+
899
+
745
900
  class TestStartDaemonLockTimeout:
746
901
  """A start that cannot get the profile lock reports failure, not an OSError."""
747
902
 
@@ -680,6 +680,7 @@ def test_listening_pids_windows_hides_netstat_console(monkeypatch):
680
680
  monkeypatch.setattr("hindsight_embed.daemon_embed_manager.platform.system", lambda: "Windows")
681
681
  monkeypatch.setattr("hindsight_embed.daemon_embed_manager.subprocess.CREATE_NO_WINDOW", 0x08000000, raising=False)
682
682
  monkeypatch.setattr("hindsight_embed.daemon_embed_manager.subprocess.run", fake_run)
683
+ monkeypatch.setattr(DaemonEmbedManager, "_windows_native_listening_pids", staticmethod(lambda _port: None))
683
684
 
684
685
  assert DaemonEmbedManager._listening_pids(9177) == [4321]
685
686
  assert calls[0][1]["creationflags"] == 0x08000000
@@ -940,12 +941,13 @@ def test_run_probe_reads_output_that_is_not_utf8():
940
941
 
941
942
 
942
943
  def test_windows_listening_pids_parses_a_localized_netstat(monkeypatch):
943
- """The existing parser needs no change: only the header carries non-ASCII."""
944
+ """A localized header does not stop the netstat fallback from reading the rows."""
944
945
  decoded = _CP936_NETSTAT.decode("utf-8", errors="replace")
945
946
  monkeypatch.setattr(
946
947
  "hindsight_embed.daemon_embed_manager.DaemonEmbedManager._run_probe",
947
948
  staticmethod(lambda cmd, timeout=None: decoded),
948
949
  )
950
+ monkeypatch.setattr(DaemonEmbedManager, "_windows_native_listening_pids", staticmethod(lambda _port: None))
949
951
 
950
952
  assert DaemonEmbedManager._windows_listening_pids(8642) == [4242]
951
953
  assert DaemonEmbedManager._windows_listening_pids(445) == [4]
@@ -930,6 +930,8 @@ def _capture_daemon_env(manager, profile: str, config: dict) -> dict[str, str]:
930
930
  patch("hindsight_embed.daemon_embed_manager.subprocess.Popen", side_effect=fake_popen),
931
931
  patch("hindsight_embed.daemon_embed_manager.time.sleep"),
932
932
  patch.object(manager, "_clear_port", return_value=True),
933
+ # Popen is stubbed, so the process lookup this would run must not be.
934
+ patch.object(manager, "_wait_for_previous_daemon_exit"),
933
935
  patch.object(manager, "_find_api_command", return_value=["hindsight-api"]),
934
936
  patch.object(manager, "is_running", side_effect=fake_is_running),
935
937
  ):
File without changes
File without changes