goals.py 83 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780
  1. """Persistent session goals — the Ralph loop for Hermes.
  2. A goal is a free-form objective that stays active across turns; after each turn an auxiliary-model
  3. judge decides whether it is satisfied. The continuation prompt is a normal user message appended via
  4. ``run_conversation`` (no system-prompt mutation or toolset swap — prompt caching stays intact). Judge
  5. failures are fail-OPEN (``continue``); the turn budget is the backstop.
  6. """
  7. from __future__ import annotations
  8. import asyncio
  9. import json
  10. import logging
  11. import os
  12. import re
  13. import subprocess
  14. import threading
  15. import time
  16. from dataclasses import dataclass, field, asdict
  17. from datetime import datetime, timezone, UTC
  18. from pathlib import Path
  19. from typing import Any, Dict, List, Optional, Tuple
  20. from hermes_cli._subprocess_compat import noninteractive_git_env
  21. from hermes_time import safe_strftime
  22. logger = logging.getLogger(__name__)
  23. # ── Constants & defaults ──────────────────────────────────────────────
  24. DEFAULT_MAX_TURNS = 20
  25. DEFAULT_JUDGE_TIMEOUT = 30.0
  26. # Judge output budget. Reasoning models burn hidden-reasoning tokens before the visible one-line
  27. # JSON verdict; 200 (the original) reliably truncated it and tripped the auto-pause. 4096 covers
  28. # every model live-tested; override via auxiliary.goal_judge.max_tokens.
  29. DEFAULT_JUDGE_MAX_TOKENS = 4096
  30. # Cap how much of the last response we send to the judge.
  31. _JUDGE_RESPONSE_SNIPPET_CHARS = 4000
  32. # Consecutive judge *parse* failures (empty / non-JSON) before the loop auto-pauses and points at
  33. # the goal_judge config. API/transport errors do NOT count — those are tracked separately below.
  34. # Guards against small models that cannot follow the strict JSON contract burning the whole budget.
  35. DEFAULT_MAX_CONSECUTIVE_PARSE_FAILURES = 3
  36. # Consecutive transport failures (401, timeout, DNS) before auto-pause: a broken API key returns
  37. # 401 every call and must not spend every turn on an unreachable judge.
  38. DEFAULT_MAX_CONSECUTIVE_TRANSPORT_FAILURES = 5
  39. # Quality gates: deterministic shell commands that must pass before the judge may declare DONE. A
  40. # failed gate short-circuits the judge — its output IS the continuation prompt, so the agent works
  41. # on concrete evidence instead of a vibe check.
  42. DEFAULT_GATE_TIMEOUT_SECONDS = 300
  43. DEFAULT_GATE_MAX_RETRIES = 3
  44. # Longest a pid/session wait barrier may hold the loop before judging resumes. Timed barriers
  45. # (``waiting_until``) carry their own deadline and are exempt.
  46. _MAX_BARRIER_WAIT_S = 30 * 60
  47. # Bounded tail of a failed gate's combined stdout/stderr fed back to the agent.
  48. _GATE_OUTPUT_TAIL_CHARS = 3000
  49. CONTINUATION_PROMPT_TEMPLATE = (
  50. "[Continuing toward your standing goal]\n"
  51. "Goal: {goal}\n\n"
  52. "Continue working toward this goal. Take the next concrete step. "
  53. "If you believe the goal is complete, state so explicitly and stop. "
  54. "If you are blocked and need input from the user, say so clearly and stop."
  55. )
  56. # With a completion contract: the block tells the agent what "done" means, how to prove it, what
  57. # not to break, scope, and when to stop — so it targets the verification surface.
  58. CONTINUATION_PROMPT_WITH_CONTRACT_TEMPLATE = (
  59. "[Continuing toward your standing goal]\n"
  60. "Goal: {goal}\n\n"
  61. "Completion contract:\n"
  62. "{contract_block}\n\n"
  63. "Continue working toward the outcome above. Take the next concrete step. "
  64. "Stay within the stated boundaries and do not violate the constraints. "
  65. "Before claiming the goal is done, satisfy the Verification criterion and "
  66. "show the concrete evidence (command output, file contents, test result). "
  67. "If you hit the stated stop condition or are otherwise blocked and need "
  68. "user input, say so clearly and stop."
  69. )
  70. # With /subgoal criteria: surfaced verbatim to the agent and to the judge.
  71. CONTINUATION_PROMPT_WITH_SUBGOALS_TEMPLATE = (
  72. "[Continuing toward your standing goal]\n"
  73. "Goal: {goal}\n\n"
  74. "Additional criteria the user added mid-loop:\n"
  75. "{subgoals_block}\n\n"
  76. "Continue working toward the goal AND all additional criteria. Take "
  77. "the next concrete step. If you believe the goal and every "
  78. "additional criterion are complete, state so explicitly and stop. "
  79. "If you are blocked and need input from the user, say so clearly "
  80. "and stop."
  81. )
  82. # Fed back when a quality gate fails: bounded output is the evidence to repair against (no judge).
  83. CONTINUATION_PROMPT_GATE_FAILED_TEMPLATE = (
  84. "[Continuing toward your standing goal — a quality gate failed]\n"
  85. "Goal: {goal}\n\n"
  86. "The quality gate command below must pass before this goal can be "
  87. "declared done, and it just failed (attempt {attempt}/{max_retries}):\n"
  88. " $ {command}\n"
  89. "Exit code: {exit_code}\n"
  90. "Output (tail):\n"
  91. "```\n"
  92. "{output}\n"
  93. "```\n\n"
  94. "Fix the underlying problem so this gate passes, then re-run it to "
  95. "confirm. Do not declare the goal complete while any gate fails. If the "
  96. "gate itself is wrong or cannot pass, say so clearly and stop."
  97. )
  98. JUDGE_SYSTEM_PROMPT = (
  99. "You are a strict judge evaluating whether an autonomous agent has "
  100. "achieved a user's stated goal. You receive the goal text, the agent's "
  101. "most recent response, and — when present — a list of background "
  102. "processes the agent has running. Decide one of four verdicts.\n\n"
  103. "DONE — the goal is fully satisfied:\n"
  104. "- The response explicitly confirms the goal was completed, OR\n"
  105. "- The response clearly shows the final deliverable was produced.\n"
  106. "DONE requires the deliverable to actually exist. If the response only "
  107. "explains why the goal cannot be reached, the verdict is BLOCKED, not "
  108. "DONE.\n\n"
  109. "BLOCKED — the goal cannot be satisfied as stated:\n"
  110. "- The response explains the goal is genuinely unachievable (impossible, "
  111. "out of scope, no valid path to the deliverable), or refuses to "
  112. "fabricate a deliverable that cannot exist, OR\n"
  113. "- The response explains progress is blocked and the next step needs "
  114. "user input to proceed.\n"
  115. "Return BLOCKED with the reason describing what is blocking. BLOCKED is "
  116. "a refusal, not a completion — never return BLOCKED for a goal that "
  117. "was achieved.\n"
  118. "When the block is an error the agent hit (an HTTP status, an API, "
  119. "sign-in or token failure), quote the error text verbatim in the reason "
  120. "and attribute it only to a provider, service or credential the response "
  121. "itself names. Never infer one the response does not name — an unnamed "
  122. "401 belongs to the model provider the agent was calling, not to some "
  123. "other service's token.\n\n"
  124. "WAIT — the goal is NOT done, but the next step is to wait for async "
  125. "work to finish rather than act again. Choose this ONLY when the agent's "
  126. "progress is genuinely gated on something running on its own:\n"
  127. "- A background process listed below is still running AND the response "
  128. "shows the agent is waiting on its result (e.g. a CI poller, build, "
  129. "test run, deploy). If the process has a session id, return it in "
  130. "``wait_on_session`` — that releases when the process exits OR its "
  131. "watch_patterns trigger fires (use this for a long-lived watcher that "
  132. "signals mid-run and may never exit). Otherwise return its pid in "
  133. "``wait_on_pid`` (releases on exit only).\n"
  134. "- The agent says it is rate-limited / backing off / must wait a fixed "
  135. "period — return seconds in ``wait_for_seconds``.\n"
  136. "- The agent has delegated subagents still running (stated below as "
  137. "active delegations) and the response says it is waiting on them with "
  138. "nothing else dispatchable — return ``wait_for_seconds`` between 600 and "
  139. "1800. Their results wake the agent on their own; re-poking it now only "
  140. "produces a status recap.\n"
  141. "Picking WAIT parks the loop without burning a turn; it resumes "
  142. "automatically when the pid exits or the time elapses. Do NOT pick WAIT "
  143. "just because work remains — only when re-poking now would be pure "
  144. "busy-work because the agent can't progress until the async thing "
  145. "finishes.\n\n"
  146. "CONTINUE — not done, and there is a concrete next step the agent can "
  147. "take right now. This is the default when in doubt.\n\n"
  148. "Reply ONLY with a single JSON object on one line. Shapes:\n"
  149. '{"verdict": "done", "reason": "<one sentence>"}\n'
  150. '{"verdict": "blocked", "reason": "<one sentence>"}\n'
  151. '{"verdict": "continue", "reason": "<one sentence>"}\n'
  152. '{"verdict": "wait", "wait_on_session": "<id>", "reason": "<one sentence>"}\n'
  153. '{"verdict": "wait", "wait_on_pid": <int>, "reason": "<one sentence>"}\n'
  154. '{"verdict": "wait", "wait_for_seconds": <int>, "reason": "<one sentence>"}\n'
  155. "The legacy shape {\"done\": <true|false>, \"reason\": \"...\"} is still "
  156. "accepted (true=done, false=continue)."
  157. )
  158. # Judge prompt line for live delegated subagents (WAIT-for-seconds vs CONTINUE).
  159. JUDGE_DELEGATIONS_BLOCK_TEMPLATE = (
  160. "Active delegations: the agent has {count} delegated subagent batch(es) still running; "
  161. "their results are delivered to it automatically when they finish.\n\n"
  162. )
  163. # Judge prompt block listing running background processes (WAIT vs CONTINUE, which pid).
  164. JUDGE_BACKGROUND_BLOCK_TEMPLATE = (
  165. "Background processes the agent currently has running (it may be waiting "
  166. "on one of these):\n{background_lines}\n\n"
  167. )
  168. JUDGE_USER_PROMPT_TEMPLATE = (
  169. "Goal:\n{goal}\n\n"
  170. "Agent's most recent response:\n{response}\n\n"
  171. "{background_block}"
  172. "Current time: {current_time}\n\n"
  173. "Is the goal satisfied — done, blocked, continue, or wait?"
  174. )
  175. # With /subgoal criteria: the judge must see ALL of them met, not just the original goal.
  176. JUDGE_USER_PROMPT_WITH_SUBGOALS_TEMPLATE = (
  177. "Goal:\n{goal}\n\n"
  178. "Additional criteria the user added mid-loop (all must also be "
  179. "satisfied for the goal to be DONE):\n{subgoals_block}\n\n"
  180. "Agent's most recent response:\n{response}\n\n"
  181. "{background_block}"
  182. "Current time: {current_time}\n\n"
  183. "Decision: For each numbered criterion above, find concrete "
  184. "evidence in the agent's response that the criterion is "
  185. "satisfied. Do not accept generic phrases like 'all requirements "
  186. "met' or 'implying it was done' — require specific evidence (a "
  187. "file contents excerpt, an output line, a command result). If "
  188. "ANY criterion lacks specific evidence in the response, the goal "
  189. "is NOT done — return CONTINUE (or WAIT if blocked on a listed "
  190. "background process).\n\n"
  191. "Is the goal AND every additional criterion satisfied?"
  192. )
  193. # With a contract: DONE strictly against the Verification criterion; a violated constraint refuses.
  194. JUDGE_USER_PROMPT_WITH_CONTRACT_TEMPLATE = (
  195. "Goal:\n{goal}\n\n"
  196. "Completion contract (the authoritative definition of done):\n"
  197. "{contract_block}\n\n"
  198. "Agent's most recent response:\n{response}\n\n"
  199. "{background_block}"
  200. "Current time: {current_time}\n\n"
  201. "Decision rules:\n"
  202. "- The goal is DONE only when the Verification criterion is satisfied AND "
  203. "the response shows concrete evidence of it (a command result, file "
  204. "contents excerpt, test/benchmark output) — not a claim like 'done' or "
  205. "'all tests pass' without evidence.\n"
  206. "- If any stated Constraint was violated, the goal is NOT done — CONTINUE.\n"
  207. "- If the response shows the agent is waiting on a listed background "
  208. "process to satisfy the Verification criterion (e.g. CI is the "
  209. "verification and it's still running), return WAIT on that process "
  210. "instead of re-poking — re-poking now would be pure busy-work.\n"
  211. "- If the response explains the work is genuinely unachievable or hits "
  212. "the stated Stop condition and needs user input, the goal is NOT done — "
  213. "return BLOCKED with the reason describing the block.\n"
  214. "- Otherwise the goal is NOT done — CONTINUE.\n\n"
  215. "Is the goal satisfied per its completion contract — done, blocked, continue, or wait?"
  216. )
  217. # /goal draft: turn a plain objective into a reviewable contract (after Codex's "draft the goal").
  218. DRAFT_CONTRACT_SYSTEM_PROMPT = (
  219. "You turn a user's plain-language objective into a structured completion "
  220. "contract for an autonomous coding agent. The contract has five fields:\n"
  221. "- outcome: the single end state that must be true when done\n"
  222. "- verification: the specific test / command / artifact that PROVES the "
  223. "outcome (must be concrete and checkable)\n"
  224. "- constraints: what must NOT change or regress\n"
  225. "- boundaries: which files, dirs, tools, or systems are in scope\n"
  226. "- stop_when: the condition under which the agent should stop and ask "
  227. "for human input instead of pushing on\n\n"
  228. "Infer sensible, specific values from the objective and any project "
  229. "context implied by it. Prefer concrete verification (a named test "
  230. "command, a build, a benchmark) over vague phrases. Keep each field to "
  231. "one or two sentences. If a field genuinely cannot be inferred, use an "
  232. "empty string for it.\n\n"
  233. "Reply ONLY with a single JSON object on one line:\n"
  234. '{"outcome": "...", "verification": "...", "constraints": "...", '
  235. '"boundaries": "...", "stop_when": "..."}'
  236. )
  237. # ── Completion contract ───────────────────────────────────────────────
  238. # The five contract fields, in display order (after OpenAI Codex's "strong goal" guidance: what
  239. # "done" means, how to prove it, what must not regress, what is in bounds, when to stop and ask).
  240. # A bare free-form goal stays fully supported — empty fields are omitted from every prompt.
  241. _CONTRACT_FIELDS = ("outcome", "verification", "constraints", "boundaries", "stop_when")
  242. _CONTRACT_LABELS = {
  243. "outcome": "Outcome", "verification": "Verification", "constraints": "Constraints",
  244. "boundaries": "Boundaries", "stop_when": "Stop when blocked",
  245. }
  246. # Inline-input aliases the user may type before a value (`verify: tests pass`, `done when: ...`).
  247. _CONTRACT_ALIASES = {
  248. "outcome": "outcome", "goal": "outcome", "done": "outcome", "done when": "outcome",
  249. "verification": "verification", "verify": "verification", "verified by": "verification",
  250. "evidence": "verification", "proof": "verification",
  251. "constraints": "constraints", "constraint": "constraints", "preserve": "constraints",
  252. "must not": "constraints", "do not change": "constraints",
  253. "boundaries": "boundaries", "boundary": "boundaries", "scope": "boundaries",
  254. "allowed": "boundaries", "files": "boundaries",
  255. "stop when": "stop_when", "stop_when": "stop_when", "blocked": "stop_when",
  256. "stop if blocked": "stop_when", "give up when": "stop_when",
  257. }
  258. @dataclass
  259. class GoalContract:
  260. """Optional structured completion contract; empty fields are omitted everywhere."""
  261. outcome: str = ""
  262. verification: str = ""
  263. constraints: str = ""
  264. boundaries: str = ""
  265. stop_when: str = ""
  266. def is_empty(self) -> bool:
  267. return not any(getattr(self, f).strip() for f in _CONTRACT_FIELDS)
  268. def to_dict(self) -> dict[str, str]:
  269. return {f: getattr(self, f) for f in _CONTRACT_FIELDS}
  270. @classmethod
  271. def from_dict(cls, data: Optional[dict[str, Any]]) -> GoalContract:
  272. if not isinstance(data, dict):
  273. return cls()
  274. return cls(**{f: str(data.get(f) or "").strip() for f in _CONTRACT_FIELDS})
  275. def render_block(self) -> str:
  276. """Non-empty fields as a labelled block; empty contract → empty string."""
  277. return "\n".join(f"- {_CONTRACT_LABELS[f]}: {getattr(self, f).strip()}" for f in _CONTRACT_FIELDS if getattr(self, f).strip())
  278. def parse_contract(text: str) -> tuple[str, GoalContract]:
  279. """Split user-typed goal text into a headline + contract from inline ``field: value`` lines.
  280. A headline without an explicit ``outcome:`` IS the outcome — it is not duplicated into the
  281. contract block (the goal text already carries it), so outcome stays empty in that case.
  282. """
  283. if not text:
  284. return "", GoalContract()
  285. headline_parts: list[str] = []
  286. fields: dict[str, list[str]] = {f: [] for f in _CONTRACT_FIELDS}
  287. for raw_line in text.splitlines():
  288. line = raw_line.strip()
  289. if not line:
  290. continue
  291. if ":" in line:
  292. prefix, _, value = line.partition(":")
  293. key = _CONTRACT_ALIASES.get(prefix.strip().lower())
  294. if key is not None and value.strip():
  295. fields[key].append(value.strip())
  296. continue
  297. headline_parts.append(line)
  298. contract = GoalContract(**{f: " ".join(v).strip() for f, v in fields.items()})
  299. return " ".join(headline_parts).strip(), contract
  300. def _render_extra_criteria(subgoals: list[str]) -> str:
  301. return "\n".join(f"- Extra criterion {i}: {text}" for i, text in enumerate(subgoals, start=1))
  302. # ── Quality gates ─────────────────────────────────────────────────────
  303. @dataclass
  304. class GoalGate:
  305. """A deterministic shell command that must pass before a goal can be done.
  306. Gates run at turn boundary BEFORE the LLM judge; a failing gate short-circuits judging and its
  307. bounded output becomes the continuation prompt.
  308. """
  309. command: str
  310. timeout_seconds: int = DEFAULT_GATE_TIMEOUT_SECONDS
  311. max_retries: int = DEFAULT_GATE_MAX_RETRIES
  312. attempts: int = 0
  313. last_exit_code: Optional[int] = None
  314. last_output_tail: str = ""
  315. def to_dict(self) -> dict[str, Any]:
  316. return asdict(self)
  317. @classmethod
  318. def from_dict(cls, data: Optional[dict[str, Any]]) -> GoalGate:
  319. if not isinstance(data, dict):
  320. return cls(command="")
  321. return cls(
  322. command=str(data.get("command") or ""),
  323. timeout_seconds=int(data.get("timeout_seconds") or DEFAULT_GATE_TIMEOUT_SECONDS),
  324. max_retries=int(data.get("max_retries") or DEFAULT_GATE_MAX_RETRIES),
  325. attempts=int(data.get("attempts") or 0),
  326. last_exit_code=(int(data["last_exit_code"]) if data.get("last_exit_code") is not None else None),
  327. last_output_tail=str(data.get("last_output_tail") or ""),
  328. )
  329. def _gate_workspace() -> tuple[Optional[str], Optional[str]]:
  330. """``(cwd, refusal)`` for this check's gates. A multi-session backend's process directory is not
  331. the session's project, so gates run in the scoped session workspace (#125369). A declared
  332. workspace that is not a directory on this host (deleted, remote, container) is a refusal: a
  333. relative gate run anywhere else would check a different project and could pass a failing goal,
  334. and no agent turn can fix it, so the caller pauses instead of retrying.
  335. No declared workspace keeps the classic resolution (TERMINAL_CWD, else the launch directory)."""
  336. from agent.runtime_cwd import resolve_agent_cwd, scoped_session_cwd
  337. declared = scoped_session_cwd()
  338. if declared:
  339. path = Path(declared).expanduser()
  340. if path.is_dir():
  341. return str(path), None
  342. return None, (f"the session workspace {declared} is not a directory on this host, "
  343. "and running gates anywhere else would check a different project")
  344. try:
  345. return str(resolve_agent_cwd()), None
  346. except OSError:
  347. return None, None # deleted launch directory: subprocess reports it per gate
  348. def run_gate(gate: GoalGate, *, cwd: Optional[str] = None) -> tuple[bool, int, str]:
  349. """Run one gate through the shell. Returns ``(passed, exit_code, output_tail)``; a timeout kills
  350. the process and counts as exit code -1."""
  351. try:
  352. # utf-8/replace: operator-configured output is arbitrary bytes; strict codepage decoding of
  353. # one unmappable byte (emoji/CJK on a non-UTF-8 Windows console) kills the reader thread and
  354. # the tail the agent needs arrives empty.
  355. proc = subprocess.run(
  356. gate.command, shell=True, capture_output=True, text=True, encoding="utf-8", errors="replace",
  357. timeout=max(1, int(gate.timeout_seconds)), cwd=cwd or None,
  358. check=False,
  359. )
  360. combined = (proc.stdout or "") + (("\n" + proc.stderr) if proc.stderr else "")
  361. return proc.returncode == 0, proc.returncode, combined[-_GATE_OUTPUT_TAIL_CHARS:]
  362. except subprocess.TimeoutExpired as exc:
  363. out = "".join(c if isinstance(c, str) else c.decode("utf-8", "replace") for c in (exc.stdout, exc.stderr) if c)
  364. return False, -1, (out + f"\n[gate timed out after {gate.timeout_seconds}s]")[-_GATE_OUTPUT_TAIL_CHARS:]
  365. except Exception as exc:
  366. return False, -1, f"[gate could not run: {type(exc).__name__}: {exc}]"
  367. # ── Goal state ────────────────────────────────────────────────────────
  368. @dataclass
  369. class GoalState:
  370. """Serializable goal state stored per session."""
  371. goal: str
  372. status: str = "active" # active | paused | done | cleared
  373. turns_used: int = 0
  374. max_turns: int = DEFAULT_MAX_TURNS
  375. created_at: float = 0.0
  376. last_turn_at: float = 0.0
  377. last_verdict: Optional[str] = None # "done" | "blocked" | "continue" | "wait" | "skipped"
  378. last_reason: Optional[str] = None
  379. paused_reason: Optional[str] = None # why we auto-paused (budget, etc.)
  380. consecutive_parse_failures: int = 0 # judge-output parse failures in a row
  381. # Tracked separately from parse failures: a broken API key returns 401 every call and must
  382. # auto-pause instead of burning the budget on an unreachable judge.
  383. consecutive_transport_failures: int = 0 # judge API/transport errors in a row
  384. # User-added criteria (/subgoal). Both the judge and continuation prompts include them.
  385. subgoals: list[str] = field(default_factory=list)
  386. # Wait barrier (judge ``wait`` verdict or ``/goal wait``): parks the loop instead of re-poking the
  387. # agent into busy-work. pid → until exit; session → until that process_registry session's OWN
  388. # trigger fires (exit OR watch_patterns match — preferred for watchers that signal mid-run);
  389. # until → wall-clock deadline. While ANY is active evaluate_after_turn returns
  390. # should_continue=False without burning a turn; cleared lazily when satisfied or by unwait/pause/
  391. # resume/clear. Defaults empty so old state_meta rows load unchanged.
  392. waiting_on_pid: Optional[int] = None
  393. waiting_on_session: Optional[str] = None
  394. waiting_until: float = 0.0
  395. # Live delegation batches when a timed WAIT was set because of them; the barrier lifts as soon
  396. # as that count drops (a batch returned), not only when the timer runs out.
  397. waiting_on_delegations: int = 0
  398. waiting_reason: Optional[str] = None
  399. waiting_since: float = 0.0
  400. contract: GoalContract = field(default_factory=GoalContract)
  401. # /goal gate add <cmd>: ALL must pass before the judge may declare done.
  402. gates: list[GoalGate] = field(default_factory=list)
  403. def to_json(self) -> str:
  404. return json.dumps(asdict(self), ensure_ascii=False)
  405. @classmethod
  406. def from_json(cls, raw: str) -> GoalState:
  407. data = json.loads(raw)
  408. raw_subgoals = data.get("subgoals") or []
  409. ints = {k: int(data.get(k) or 0) for k in ("turns_used", "consecutive_parse_failures", "consecutive_transport_failures", "waiting_on_delegations")}
  410. floats = {k: float(data.get(k) or 0.0) for k in ("created_at", "last_turn_at", "waiting_until", "waiting_since")}
  411. return cls(
  412. goal=data.get("goal", ""),
  413. status=data.get("status", "active"),
  414. max_turns=int(data.get("max_turns") or DEFAULT_MAX_TURNS),
  415. last_verdict=data.get("last_verdict"),
  416. last_reason=data.get("last_reason"),
  417. paused_reason=data.get("paused_reason"),
  418. subgoals=[str(s).strip() for s in raw_subgoals if str(s).strip()] if isinstance(raw_subgoals, list) else [],
  419. waiting_on_pid=(int(data["waiting_on_pid"]) if data.get("waiting_on_pid") else None),
  420. waiting_on_session=(str(data["waiting_on_session"]) if data.get("waiting_on_session") else None),
  421. waiting_reason=data.get("waiting_reason"),
  422. contract=GoalContract.from_dict(data.get("contract")),
  423. gates=[
  424. GoalGate.from_dict(g) for g in (data.get("gates") or [])
  425. if isinstance(g, dict) and str(g.get("command") or "").strip()
  426. ],
  427. **ints, **floats,
  428. )
  429. def has_contract(self) -> bool:
  430. return self.contract is not None and not self.contract.is_empty()
  431. def render_subgoals_block(self) -> str:
  432. """Numbered ``- N. text`` block; empty when there are no subgoals."""
  433. return "\n".join(f"- {i}. {text}" for i, text in enumerate(self.subgoals, start=1))
  434. def clear_wait(self) -> None:
  435. self.waiting_on_pid = None
  436. self.waiting_on_session = None
  437. self.waiting_until = 0.0
  438. self.waiting_on_delegations = 0
  439. self.waiting_reason = None
  440. self.waiting_since = 0.0
  441. # ── Persistence (SessionDB state_meta) ────────────────────────────────
  442. def _meta_key(session_id: str) -> str:
  443. return f"goal:{session_id}"
  444. _DB_CACHE: dict[str, Any] = {}
  445. _DB_BOOTSTRAP_LOCK = threading.Lock()
  446. _DB_BOOTSTRAP_INFLIGHT: dict[str, threading.Event] = {}
  447. # How long a loop-thread caller waits for an ALREADY-RUNNING bootstrap before degrading to None.
  448. # Normal SessionDB init is ~10-100ms so a mid-bootstrap call usually picks the cached instance up;
  449. # a contended init (locked state.db mid-migration) exceeds it and degrades. Far under the
  450. # watchdog's probe window.
  451. _DB_BOOTSTRAP_LOOP_WAIT_S = 0.25
  452. # The call that STARTS the bootstrap (cold cache) waits this long instead. A fresh state.db init
  453. # (schema DDL, FTS tables, first hermes_cli.config import) measures ~300ms warm and more on slow
  454. # CI — well past 0.25s, which used to drop the first /goal write ("Goal set" but nothing
  455. # persisted). Only the kick call pays this one-time stall; later calls keep the short window.
  456. _DB_BOOTSTRAP_INIT_WAIT_S = 1.5
  457. def _bootstrap_session_db(home: str, done: threading.Event) -> None:
  458. """Construct SessionDB off-loop and populate the cache (worker thread)."""
  459. try:
  460. db = _acquire_session_db(home)
  461. except Exception as exc: # pragma: no cover
  462. logger.debug("GoalManager: background SessionDB() raised (%s)", exc)
  463. db = None
  464. with _DB_BOOTSTRAP_LOCK:
  465. if db is not None and home not in _DB_CACHE:
  466. _DB_CACHE[home] = db
  467. db = None
  468. _DB_BOOTSTRAP_INFLIGHT.pop(home, None)
  469. if db is not None: # lost the race; drop our reference
  470. _release_session_db(db)
  471. done.set()
  472. def _get_session_db() -> Optional[Any]:
  473. """Cached SessionDB per HERMES_HOME (profile switches pick the right DB); None on any failure.
  474. Never constructs SessionDB on an event-loop thread: a cache miss there kicks a one-shot background
  475. bootstrap and waits a bounded grace window (the kick call waits ``_DB_BOOTSTRAP_INIT_WAIT_S`` so a
  476. healthy cold init completes and the first write isn't dropped).
  477. """
  478. try:
  479. from hermes_constants import get_hermes_home
  480. home = str(get_hermes_home())
  481. except Exception as exc: # pragma: no cover
  482. logger.debug("GoalManager: SessionDB bootstrap failed (%s)", exc)
  483. return None
  484. cached = _DB_CACHE.get(home)
  485. if cached is not None and _registry_tore_down(cached):
  486. # ``hermes profile delete`` force-closes every handle under the profile home
  487. # (``hermes_state_registry.close_all_under``) before rmtree; a same-name recreate in this
  488. # process must acquire a fresh handle, not keep writing into the torn-down one.
  489. with _DB_BOOTSTRAP_LOCK:
  490. if _DB_CACHE.get(home) is cached:
  491. del _DB_CACHE[home]
  492. cached = None
  493. if cached is not None:
  494. return cached
  495. try:
  496. asyncio.get_running_loop()
  497. except RuntimeError:
  498. on_loop_thread = False
  499. else:
  500. on_loop_thread = True
  501. if on_loop_thread:
  502. with _DB_BOOTSTRAP_LOCK:
  503. # Re-check under the lock: a bootstrap may have finished since the unlocked read.
  504. cached = _DB_CACHE.get(home)
  505. if cached is not None:
  506. return cached
  507. done = _DB_BOOTSTRAP_INFLIGHT.get(home)
  508. wait = _DB_BOOTSTRAP_LOOP_WAIT_S # already running: brief grace window only
  509. if done is None:
  510. done = _DB_BOOTSTRAP_INFLIGHT[home] = threading.Event()
  511. threading.Thread(target=_bootstrap_session_db, args=(home, done), name="goals-sessiondb-bootstrap", daemon=True).start()
  512. wait = _DB_BOOTSTRAP_INIT_WAIT_S # kick call pays the one-time init cost
  513. done.wait(wait)
  514. return _DB_CACHE.get(home)
  515. try:
  516. db = _acquire_session_db(home)
  517. except Exception as exc: # pragma: no cover
  518. logger.debug("GoalManager: SessionDB() raised (%s)", exc)
  519. return None
  520. with _DB_BOOTSTRAP_LOCK:
  521. existing = _DB_CACHE.get(home)
  522. if existing is not None:
  523. # A concurrent bootstrap won the race; drop our reference so connections don't leak.
  524. _release_session_db(db)
  525. return existing
  526. _DB_CACHE[home] = db
  527. return db
  528. def _acquire_session_db(home: str):
  529. """The registry's shared handle for ``home/state.db``. A bare ``SessionDB()`` here was a SECOND
  530. writer per profile beside the gateway's registry handle — its own token-writer thread and
  531. close-time checkpoint (the #90837 corruption shape), doubled under multiplexing."""
  532. from hermes_state_registry import acquire
  533. return acquire(Path(home) / "state.db")
  534. def _release_session_db(db) -> None:
  535. from hermes_state_registry import release_or_close
  536. try:
  537. release_or_close(db)
  538. except Exception:
  539. pass
  540. def _registry_tore_down(db) -> bool:
  541. """True once the registry force-closed *db* (``close_all`` / ``close_all_under`` clear the
  542. shared-owned flag at teardown); every handle cached here was acquired through the registry, so a
  543. cleared flag means the connection is gone and the cache entry is stale."""
  544. return getattr(db, "_shared_registry_owned", True) is False
  545. def _warn_dropped_write(manager: str, kind: str, session_id: str) -> None:
  546. """WARN on a dropped state write — the reply already told the user the state was set. One shared
  547. message keeps goal, loop and heartbeat logs greppable as one bug class."""
  548. logger.warning(
  549. "%s: %s for %s not persisted — session DB unavailable "
  550. "(bootstrap window exceeded, in-memory state still active)",
  551. manager, kind, session_id,
  552. )
  553. def load_goal(session_id: str) -> Optional[GoalState]:
  554. """Load the goal for a session, or None if none exists."""
  555. if not session_id:
  556. return None
  557. db = _get_session_db()
  558. if db is None:
  559. return None
  560. try:
  561. raw = db.get_meta(_meta_key(session_id))
  562. except Exception as exc:
  563. logger.debug("GoalManager: get_meta failed: %s", exc)
  564. return None
  565. if not raw:
  566. return None
  567. try:
  568. return GoalState.from_json(raw)
  569. except Exception as exc:
  570. logger.warning("GoalManager: could not parse stored goal for %s: %s", session_id, exc)
  571. return None
  572. def save_goal(session_id: str, state: GoalState) -> None:
  573. """Persist a goal to SessionDB. No-op if DB unavailable."""
  574. if not session_id:
  575. return
  576. db = _get_session_db()
  577. if db is None:
  578. _warn_dropped_write("GoalManager", "goal", session_id)
  579. return
  580. try:
  581. db.set_meta(_meta_key(session_id), state.to_json())
  582. except Exception as exc:
  583. logger.debug("GoalManager: set_meta failed: %s", exc)
  584. def clear_goal(session_id: str) -> None:
  585. """Mark a goal cleared in the DB (preserved for audit, status=cleared)."""
  586. state = load_goal(session_id)
  587. if state is None:
  588. return
  589. state.status = "cleared"
  590. save_goal(session_id, state)
  591. def migrate_goal_to_session(old_session_id: str, new_session_id: str, *, reason: str = "") -> bool:
  592. """Carry a persistent /goal from a parent session to its continuation. Best-effort, never raises
  593. (a failure here must not block compression). Returns True when a goal was migrated.
  594. Context compression rotates ``session_id`` to a fresh child session, but ``load_goal`` does a flat
  595. ``goal:<session_id>`` lookup with no parent-lineage walk — so an active goal silently dies at the
  596. compaction boundary (#33618). Copy the goal onto the new session and archive the old row as ``cleared``
  597. so exactly one active goal row exists per logical conversation (avoids the "two active goals" hazard of
  598. a pure copy).
  599. """
  600. if not old_session_id or not new_session_id or old_session_id == new_session_id:
  601. return False
  602. try:
  603. state = load_goal(old_session_id)
  604. if state is None or state.status == "cleared":
  605. return False
  606. # Don't clobber a goal already set on the child (e.g. a resumed lineage).
  607. if load_goal(new_session_id) is not None:
  608. return False
  609. save_goal(new_session_id, state)
  610. # Archive the parent's row so it isn't double-counted as active.
  611. clear_goal(old_session_id)
  612. logger.debug("GoalManager: migrated goal %s -> %s (%s)", old_session_id, new_session_id, reason or "rotation")
  613. return True
  614. except Exception as exc: # pragma: no cover - defensive
  615. logger.debug("GoalManager: goal migration failed: %s", exc)
  616. return False
  617. # ── Judge ─────────────────────────────────────────────────────────────
  618. def _truncate(text: str, limit: int) -> str:
  619. if not text:
  620. return ""
  621. return text if len(text) <= limit else text[:limit] + "… [truncated]"
  622. def _pid_alive(pid: int) -> bool:
  623. """Liveness via ``gateway.status._pid_exists`` (psutil + ctypes/POSIX fallback). Never uses
  624. ``os.kill(pid, 0)``: on Windows that routes to CTRL_C_EVENT and hard-kills the target's console
  625. group (bpo-14484)."""
  626. if not pid or pid <= 0:
  627. return False
  628. try:
  629. from gateway.status import _pid_exists
  630. return bool(_pid_exists(int(pid)))
  631. except Exception:
  632. pass
  633. try:
  634. import psutil # type: ignore
  635. return bool(psutil.pid_exists(int(pid)))
  636. except Exception:
  637. return False
  638. def _session_waiting(session_id: str) -> bool:
  639. """True while the process_registry session is running and its trigger hasn't fired. Fail-safe:
  640. any import/registry error yields False so a stale barrier can never wedge the loop."""
  641. if not session_id:
  642. return False
  643. try:
  644. from tools.process_registry import process_registry
  645. return bool(process_registry.is_session_waiting(session_id))
  646. except Exception:
  647. return False
  648. _JSON_OBJECT_RE = re.compile(r"\{.*?\}", re.DOTALL)
  649. def _goal_judge_setting(key: str, default, cast):
  650. """Resolve ``auxiliary.goal_judge.<key>``; non-positive/garbage falls back to ``default``
  651. rather than crashing the loop. ``load_config()`` is cached on (mtime, size) so this is cheap."""
  652. try:
  653. from hermes_cli.config import load_config
  654. value = cast((load_config().get("auxiliary") or {}).get("goal_judge", {}).get(key, default))
  655. if value > 0:
  656. return value
  657. except Exception:
  658. pass
  659. return default
  660. def _goal_judge_max_tokens() -> int:
  661. return _goal_judge_setting("max_tokens", DEFAULT_JUDGE_MAX_TOKENS, int)
  662. def _goal_judge_timeout() -> float:
  663. return _goal_judge_setting("timeout", DEFAULT_JUDGE_TIMEOUT, float)
  664. def _extract_json_object(raw: str) -> Optional[dict[str, Any]]:
  665. """Best-effort: strip code fences, parse the blob, else pull the first ``{...}`` out."""
  666. if not raw:
  667. return None
  668. text = raw.strip()
  669. if text.startswith("```"):
  670. text = text.strip("`")
  671. nl = text.find("\n") # peel off leading json/JSON tag
  672. if nl != -1:
  673. text = text[nl + 1:]
  674. try:
  675. data = json.loads(text)
  676. except Exception:
  677. match = _JSON_OBJECT_RE.search(text)
  678. if not match:
  679. return None
  680. try:
  681. data = json.loads(match.group(0))
  682. except Exception:
  683. return None
  684. return data if isinstance(data, dict) else None
  685. def _parse_judge_response(raw: str) -> tuple[str, str, bool, Optional[dict[str, Any]]]:
  686. """Parse the judge's reply, fail-open. Returns ``(verdict, reason, parse_failed, wait_directive)``.
  687. ``parse_failed`` flags non-JSON output so callers can auto-pause after N in a row.
  688. ``wait_directive`` is ``{"session_id"}`` / ``{"pid"}`` / ``{"seconds"}`` for a ``wait``
  689. verdict; a wait with no target is downgraded to ``continue``. Accepts ``{"verdict": ...}`` and
  690. the legacy ``{"done": <bool>}`` shape.
  691. """
  692. if not raw:
  693. return "continue", "judge returned empty response", True, None
  694. data = _extract_json_object(raw)
  695. if data is None:
  696. return "continue", f"judge reply was not JSON: {_truncate(raw, 200)!r}", True, None
  697. reason = str(data.get("reason") or "").strip() or "no reason provided"
  698. verdict_raw = data.get("verdict")
  699. if isinstance(verdict_raw, str):
  700. verdict = verdict_raw.strip().lower()
  701. else:
  702. done_val = data.get("done")
  703. done = done_val.strip().lower() in {"true", "yes", "1", "done"} if isinstance(done_val, str) else bool(done_val)
  704. verdict = "done" if done else "continue"
  705. if verdict not in {"done", "blocked", "continue", "wait"}:
  706. verdict = "continue"
  707. if verdict != "wait":
  708. return verdict, reason, False, None
  709. def _first_int(*keys: str) -> Optional[int]:
  710. for k in keys:
  711. try:
  712. iv = int(data[k]) if data.get(k) is not None else 0
  713. except (TypeError, ValueError):
  714. continue
  715. if iv > 0:
  716. return iv
  717. return None
  718. # Prefer session (releases on the process's own trigger), then pid (exit only), then seconds.
  719. sess = data.get("wait_on_session") or data.get("session_id") or data.get("wait_session")
  720. if isinstance(sess, str) and sess.strip():
  721. return "wait", reason, False, {"session_id": sess.strip()}
  722. pid = _first_int("wait_on_pid", "pid", "wait_pid")
  723. if pid is not None:
  724. return "wait", reason, False, {"pid": pid}
  725. seconds = _first_int("wait_for_seconds", "seconds", "wait_seconds")
  726. if seconds is not None:
  727. return "wait", reason, False, {"seconds": seconds}
  728. return "continue", f"{reason} (wait verdict had no target — continuing)", False, None
  729. def _render_background_block(background_processes: Optional[list[dict[str, Any]]]) -> str:
  730. """Render RUNNING ``process_registry.list_sessions()`` entries for the judge prompt. Empty string
  731. when nothing is running, so the prompt stays byte-identical to the no-background case."""
  732. lines: list[str] = []
  733. for p in background_processes or []:
  734. if not isinstance(p, dict) or p.get("status") == "exited" or not p.get("pid"):
  735. continue
  736. cmd = _truncate(str(p.get("command") or "").replace("\n", " ").strip(), 120)
  737. tail = _truncate(str(p.get("output_preview") or "").replace("\n", " ").strip(), 120)
  738. line = f"- pid {p['pid']}"
  739. if p.get("session_id"):
  740. line += f" / session {p['session_id']}"
  741. line += f": {cmd}"
  742. if p.get("uptime_seconds") is not None:
  743. line += f" (running {p['uptime_seconds']}s)"
  744. # Surface the process's own trigger so the judge can wait on a mid-run signal, not just exit.
  745. wps = p.get("watch_patterns")
  746. if wps:
  747. hit = " [already matched]" if p.get("watch_hit") else ""
  748. line += f" | watch_patterns={wps}{hit}"
  749. elif p.get("notify_on_complete"):
  750. line += " | notify_on_complete"
  751. if tail:
  752. line += f" | recent output: {tail}"
  753. lines.append(line)
  754. if not lines:
  755. return ""
  756. return JUDGE_BACKGROUND_BLOCK_TEMPLATE.format(background_lines="\n".join(lines))
  757. def _call_goal_judge_llm(call_llm, system_prompt: str, user_prompt: str, timeout: Optional[float]) -> str:
  758. """Route through call_llm so auxiliary.goal_judge.* config (provider/model, extra_body,
  759. reasoning_effort, retries) all apply. Returns the raw reply text."""
  760. # See #35566.
  761. # Route through call_llm — same #35566 fix as the judge call above.
  762. resp = call_llm(
  763. task="goal_judge",
  764. messages=[{"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}],
  765. temperature=0, max_tokens=_goal_judge_max_tokens(), timeout=timeout,
  766. )
  767. try:
  768. return resp.choices[0].message.content or ""
  769. except Exception:
  770. return ""
  771. def judge_goal(
  772. goal: str,
  773. last_response: str,
  774. *,
  775. timeout: Optional[float] = None,
  776. subgoals: Optional[list[str]] = None,
  777. background_processes: Optional[list[dict[str, Any]]] = None,
  778. contract: Optional[GoalContract] = None,
  779. active_delegations: int = 0,
  780. ) -> tuple[str, str, bool, Optional[dict[str, Any]], bool]:
  781. """Ask the auxiliary model whether the goal is satisfied.
  782. Returns ``(verdict, reason, parse_failed, wait_directive, transport_failed)``; verdict is done /
  783. blocked / continue / wait / skipped. ``parse_failed`` means unusable output; transport errors
  784. set ``transport_failed`` instead and fail-open to ``continue``.
  785. """
  786. if not goal.strip():
  787. return "skipped", "empty goal", False, None, False
  788. if not last_response.strip():
  789. return "continue", "empty response (nothing to evaluate)", False, None, False
  790. if timeout is None:
  791. timeout = _goal_judge_timeout() # the declared default is the config key, not the constant
  792. try:
  793. from agent.auxiliary_client import call_llm
  794. from agent.auxiliary_unavailable import AuxiliaryClientUnavailable
  795. except Exception as exc:
  796. logger.debug("goal judge: auxiliary client import failed: %s", exc)
  797. return "continue", "auxiliary client unavailable", False, None, False
  798. # Prompt priority: contract > subgoals > plain. With both, subgoals fold into the contract
  799. # block as extra criteria so the judge sees a single source of truth.
  800. clean_subgoals = [s.strip() for s in (subgoals or []) if s and s.strip()]
  801. common = dict(
  802. goal=_truncate(goal, 2000),
  803. response=_truncate(last_response, _JUDGE_RESPONSE_SNIPPET_CHARS),
  804. background_block=_render_background_block(background_processes)
  805. + (JUDGE_DELEGATIONS_BLOCK_TEMPLATE.format(count=active_delegations) if active_delegations > 0 else ""),
  806. current_time=safe_strftime(datetime.now(tz=UTC).astimezone(), "%Y-%m-%d %H:%M:%S %Z"),
  807. )
  808. if contract is not None and not contract.is_empty():
  809. contract_block = contract.render_block()
  810. if clean_subgoals:
  811. contract_block = f"{contract_block}\n{_render_extra_criteria(clean_subgoals)}"
  812. prompt = JUDGE_USER_PROMPT_WITH_CONTRACT_TEMPLATE.format(contract_block=_truncate(contract_block, 2500), **common)
  813. elif clean_subgoals:
  814. subgoals_block = "\n".join(f"- {i}. {text}" for i, text in enumerate(clean_subgoals, start=1))
  815. prompt = JUDGE_USER_PROMPT_WITH_SUBGOALS_TEMPLATE.format(subgoals_block=_truncate(subgoals_block, 2000), **common)
  816. else:
  817. prompt = JUDGE_USER_PROMPT_TEMPLATE.format(**common)
  818. try:
  819. raw = _call_goal_judge_llm(call_llm, JUDGE_SYSTEM_PROMPT, prompt, timeout)
  820. except AuxiliaryClientUnavailable as exc:
  821. # No client at all (e.g. a dead Nous refresh token): name the cause so the user is sent to
  822. # re-authenticate, not to context-length / model debugging (#42177). Still fails open.
  823. logger.info("goal judge: auxiliary client unavailable (%s) — falling through to continue", exc)
  824. return "continue", f"goal_judge auxiliary client unavailable: {exc}", False, None, True
  825. except Exception as exc:
  826. logger.info("goal judge: API call failed (%s) — falling through to continue", exc)
  827. return "continue", f"judge error: {type(exc).__name__}", False, None, True
  828. verdict, reason, parse_failed, wait_directive = _parse_judge_response(raw)
  829. logger.info("goal judge: verdict=%s reason=%s%s", verdict, _truncate(reason, 120),
  830. f" wait={wait_directive}" if wait_directive else "")
  831. return verdict, reason, parse_failed, wait_directive, False
  832. def count_active_delegations(session_id: Optional[str]) -> int:
  833. """Live async delegation batches spawned by this session (fail-safe 0)."""
  834. if not session_id:
  835. return 0
  836. try:
  837. from tools.async_delegation import _LIVE_STATES, _session_records
  838. return len(_session_records(_LIVE_STATES, "", "", str(session_id)))
  839. except Exception:
  840. return 0
  841. # `/goal <text>` kicks the loop by sending the goal as the next user turn. When that text IS what
  842. # the user just said (a pasted handoff note, a plan the agent already has), re-sending it makes the
  843. # agent spend a turn deciding it is a replay (11 API calls, 6 min, in one run) and duplicates ~2k
  844. # tokens of context. The pointer is used only when the goal is substantially the WHOLE last
  845. # message: a short goal that merely appears inside a longer one ("ship the API" after a message
  846. # offering API or UI work) selects one option, and two different goals must not kick identically.
  847. GOAL_ALREADY_SEEN_KICK = "[Goal set] Continue with the goal you were just given; there is no need to re-read it."
  848. _GOAL_REPASTE_MIN_CHARS = 400
  849. _GOAL_REPASTE_MIN_SHARE = 0.8
  850. def goal_kick_prompt(goal: str, last_user_message: Any) -> str:
  851. """The goal text, or ``GOAL_ALREADY_SEEN_KICK`` when ``last_user_message`` is essentially that text."""
  852. content = last_user_message
  853. if isinstance(content, list):
  854. content = " ".join(str(b.get("text", "")) for b in content if isinstance(b, dict))
  855. goal_norm, last_norm = " ".join(str(goal or "").split()), " ".join(str(content or "").split())
  856. if (
  857. len(goal_norm) >= _GOAL_REPASTE_MIN_CHARS
  858. and goal_norm in last_norm
  859. and len(goal_norm) >= _GOAL_REPASTE_MIN_SHARE * len(last_norm)
  860. ):
  861. return GOAL_ALREADY_SEEN_KICK
  862. return goal
  863. def last_user_message_content(history: Any) -> Any:
  864. """Content of the newest ``role == "user"`` message in an OpenAI-shaped history, else ``""``."""
  865. for msg in reversed(history or []):
  866. if isinstance(msg, dict) and msg.get("role") == "user":
  867. return msg.get("content")
  868. return ""
  869. def last_user_message_from_db(session_id: Optional[str]) -> Any:
  870. """Newest user message of ``session_id`` from the SessionDB (gateway/TUI surfaces have no live
  871. history object at slash-command time); ``""`` on any error."""
  872. if not session_id:
  873. return ""
  874. try:
  875. db = _get_session_db()
  876. if db is None:
  877. return ""
  878. rows = db.get_messages(str(session_id), limit=20, latest=True)
  879. return last_user_message_content(rows)
  880. except Exception:
  881. return ""
  882. def gather_background_processes(task_id: Optional[str] = None, *, owner_task_id: Optional[str] = None) -> list[dict[str, Any]]:
  883. """Fail-safe snapshot of RUNNING ``process_registry`` sessions for the judge; ``[]`` on any error
  884. so the loop degrades to its pre-wait-barrier behavior.
  885. ``owner_task_id`` restricts the snapshot to processes the goal's OWN session spawned. The registry's
  886. ``task_id`` is the container key, which collapses to one value for every agent in the process, so
  887. without this filter a fan-out parent's judge saw every subagent's pollers and parked the goal on a
  888. grandchild's ``proc_*`` session (one run: 7 of 7 root verdicts were WAIT on child-owned processes;
  889. parked 3 h 22 min at the end while nothing of its own was running)."""
  890. try:
  891. from tools.process_registry import process_registry
  892. sessions = process_registry.list_sessions(task_id=task_id) or []
  893. except Exception as exc:
  894. logger.debug("gather_background_processes failed: %s", exc)
  895. return []
  896. running = [s for s in sessions if isinstance(s, dict) and s.get("status") != "exited"]
  897. if owner_task_id:
  898. running = [s for s in running if str(s.get("owner_task_id") or s.get("task_id") or "") == str(owner_task_id)]
  899. return running
  900. def draft_contract(objective: str, *, timeout: Optional[float] = None) -> Optional[GoalContract]:
  901. """Expand a plain-language objective into a completion contract via the ``goal_judge`` auxiliary
  902. task (a side LLM call, not a conversation turn). None when unavailable or unparseable."""
  903. objective = (objective or "").strip()
  904. if not objective:
  905. return None
  906. if timeout is None:
  907. # The declared default for this path is the config key, not the module constant — see
  908. # _goal_judge_timeout (#91022).
  909. # Same config-backed default as judge_goal (#91022).
  910. timeout = _goal_judge_timeout()
  911. try:
  912. from agent.auxiliary_client import call_llm
  913. except Exception as exc:
  914. logger.debug("goal draft: auxiliary client import failed: %s", exc)
  915. return None
  916. try:
  917. raw = _call_goal_judge_llm(call_llm, DRAFT_CONTRACT_SYSTEM_PROMPT, f"Objective:\n{_truncate(objective, 4000)}", timeout)
  918. except Exception as exc:
  919. logger.info("goal draft: API call failed (%s)", exc)
  920. return None
  921. data = _extract_json_object(raw)
  922. if not isinstance(data, dict):
  923. logger.debug("goal draft: reply was not JSON: %r", _truncate(raw, 200))
  924. return None
  925. contract = GoalContract.from_dict(data)
  926. return None if contract.is_empty() else contract
  927. # ── GoalManager — the orchestration surface CLI + gateway talk to ──────
  928. def _decision(status, should_continue: bool, prompt: Optional[str], verdict: str, reason: str, message: str) -> dict[str, Any]:
  929. return {"status": status, "should_continue": should_continue, "continuation_prompt": prompt,
  930. "verdict": verdict, "reason": reason, "message": message}
  931. _JUDGE_CONFIG_HINT = (
  932. "~/.hermes/config.yaml:\n auxiliary:\n goal_judge:\n provider: {provider}\n model: {model}\n"
  933. "Then /goal resume to continue."
  934. )
  935. class GoalManager:
  936. """Per-session goal state + continuation decisions.
  937. The CLI and gateway each hold one per live session. ``evaluate_after_turn`` calls the judge and
  938. returns the decision dict that drives the next turn; ``next_continuation_prompt`` is the
  939. canonical user-role message to feed back into ``run_conversation``.
  940. """
  941. def __init__(self, session_id: str, *, default_max_turns: int = DEFAULT_MAX_TURNS):
  942. self.session_id = session_id
  943. self.default_max_turns = int(default_max_turns or DEFAULT_MAX_TURNS)
  944. self._state: Optional[GoalState] = load_goal(session_id)
  945. def refresh(self) -> None:
  946. """Re-read state from the DB (another writer, e.g. a tool, moved it)."""
  947. self._state = load_goal(self.session_id)
  948. # --- introspection ------------------------------------------------
  949. @property
  950. def state(self) -> Optional[GoalState]:
  951. return self._state
  952. def is_active(self) -> bool:
  953. return self._state is not None and self._state.status == "active"
  954. def has_goal(self) -> bool:
  955. return self._state is not None and self._state.status in {"active", "paused"}
  956. def has_contract(self) -> bool:
  957. return self._state is not None and self._state.has_contract()
  958. def status_line(self) -> str:
  959. s = self._state
  960. if s is None or s.status == "cleared":
  961. return "No active goal. Set one with /goal <text>."
  962. turns = f"{s.turns_used}/{s.max_turns} turns"
  963. sub = f", {len(s.subgoals)} subgoal{'s' if len(s.subgoals) != 1 else ''}" if s.subgoals else ""
  964. con = ", contract" if self.has_contract() else ""
  965. gat = f", {len(s.gates)} gate{'s' if len(s.gates) != 1 else ''}" if s.gates else ""
  966. meta = f"{turns}{sub}{con}{gat}"
  967. if s.status == "active":
  968. if s.waiting_on_session and _session_waiting(s.waiting_on_session):
  969. return f"⏳ Goal (parked on {s.waiting_reason or f'session {s.waiting_on_session}'}, {meta}): {s.goal}"
  970. if s.waiting_on_pid and _pid_alive(s.waiting_on_pid):
  971. return f"⏳ Goal (parked on {s.waiting_reason or f'pid {s.waiting_on_pid}'}, {meta}): {s.goal}"
  972. if s.waiting_until and time.time() < s.waiting_until:
  973. remaining = int(s.waiting_until - time.time())
  974. wr = s.waiting_reason or f"{remaining}s"
  975. return f"⏳ Goal (parked {remaining}s — {wr}, {meta}): {s.goal}"
  976. return f"⊙ Goal (active, {meta}): {s.goal}"
  977. if s.status == "paused":
  978. extra = f" — {s.paused_reason}" if s.paused_reason else ""
  979. return f"⏸ Goal (paused, {meta}{extra}): {s.goal}"
  980. if s.status == "done":
  981. return f"✓ Goal done ({meta}): {s.goal}"
  982. return f"Goal ({s.status}, {meta}): {s.goal}"
  983. # --- mutation -----------------------------------------------------
  984. def _save(self) -> Optional[GoalState]:
  985. save_goal(self.session_id, self._state)
  986. return self._state
  987. def _require_goal(self) -> GoalState:
  988. if self._state is None or not self.has_goal():
  989. raise RuntimeError("no active goal")
  990. return self._state
  991. def _require_active(self) -> GoalState:
  992. if self._state is None or self._state.status != "active":
  993. raise RuntimeError("no active goal to park")
  994. return self._state
  995. def _pause_state(self, reason: str) -> None:
  996. self._state.status = "paused"
  997. self._state.paused_reason = reason
  998. self._save()
  999. def _pause_decision(self, paused_reason: str, verdict: str, reason: str, message: str) -> dict[str, Any]:
  1000. self._pause_state(paused_reason)
  1001. return _decision("paused", False, None, verdict, reason, message)
  1002. def set(self, goal: str, *, max_turns: Optional[int] = None, contract: Optional[GoalContract] = None) -> GoalState:
  1003. goal = (goal or "").strip()
  1004. if not goal:
  1005. raise ValueError("goal text is empty")
  1006. self._state = GoalState(
  1007. goal=goal, status="active", turns_used=0, created_at=time.time(), last_turn_at=0.0,
  1008. max_turns=int(max_turns) if max_turns else self.default_max_turns,
  1009. contract=contract if contract is not None else GoalContract(),
  1010. )
  1011. return self._save()
  1012. def set_contract(self, contract: GoalContract) -> Optional[GoalState]:
  1013. """Attach or replace the completion contract on the active goal."""
  1014. if self._state is None:
  1015. return None
  1016. self._state.contract = contract or GoalContract()
  1017. return self._save()
  1018. def pause(self, reason: str = "user-paused") -> Optional[GoalState]:
  1019. if not self._state:
  1020. return None
  1021. self._state.status = "paused"
  1022. self._state.paused_reason = reason
  1023. self._state.clear_wait() # a wait barrier is meaningless once paused
  1024. return self._save()
  1025. def resume(self, *, reset_budget: bool = True) -> Optional[GoalState]:
  1026. if not self._state:
  1027. return None
  1028. self._state.status = "active"
  1029. self._state.paused_reason = None
  1030. self._state.clear_wait() # resuming starts fresh
  1031. if reset_budget:
  1032. self._state.turns_used = 0
  1033. return self._save()
  1034. def clear(self) -> None:
  1035. if self._state is None:
  1036. return
  1037. self._state.status = "cleared"
  1038. self._save()
  1039. self._state = None
  1040. def mark_done(self, reason: str) -> None:
  1041. if not self._state:
  1042. return
  1043. self._state.status = "done"
  1044. self._state.last_verdict = "done"
  1045. self._state.last_reason = reason
  1046. self._save()
  1047. # --- /subgoal user controls ---------------------------------------
  1048. def add_subgoal(self, text: str) -> str:
  1049. """Append a user-added criterion; raises ``RuntimeError`` without ``has_goal()``."""
  1050. state = self._require_goal()
  1051. text = (text or "").strip()
  1052. if not text:
  1053. raise ValueError("subgoal text is empty")
  1054. state.subgoals.append(text)
  1055. self._save()
  1056. return text
  1057. def _pop_item(self, attr: str, index_1based: int):
  1058. items = getattr(self._require_goal(), attr)
  1059. idx = int(index_1based) - 1
  1060. if idx < 0 or idx >= len(items):
  1061. raise IndexError(f"index out of range (1..{len(items)})")
  1062. removed = items.pop(idx)
  1063. self._save()
  1064. return removed
  1065. def _clear_items(self, attr: str) -> int:
  1066. state = self._require_goal()
  1067. prev = len(getattr(state, attr))
  1068. setattr(state, attr, [])
  1069. self._save()
  1070. return prev
  1071. def remove_subgoal(self, index_1based: int) -> str:
  1072. """Remove a subgoal by 1-based index. Returns the removed text."""
  1073. return self._pop_item("subgoals", index_1based)
  1074. def clear_subgoals(self) -> int:
  1075. """Wipe all subgoals. Returns the previous count."""
  1076. return self._clear_items("subgoals")
  1077. def render_subgoals(self) -> str:
  1078. """Public helper for the /subgoal slash command."""
  1079. if self._state is None:
  1080. return "(no active goal)"
  1081. return self._state.render_subgoals_block() or "(no subgoals — use /subgoal <text> to add criteria)"
  1082. # --- /goal gate quality gates ---------------------------------------
  1083. def add_gate(self, command: str, *, timeout_seconds: Optional[int] = None, max_retries: Optional[int] = None) -> GoalGate:
  1084. """Append a quality-gate command; raises ``RuntimeError`` without ``has_goal()``."""
  1085. state = self._require_goal()
  1086. command = (command or "").strip()
  1087. if not command:
  1088. raise ValueError("gate command is empty")
  1089. gate = GoalGate(
  1090. command=command,
  1091. timeout_seconds=int(timeout_seconds) if timeout_seconds else DEFAULT_GATE_TIMEOUT_SECONDS,
  1092. max_retries=int(max_retries) if max_retries else DEFAULT_GATE_MAX_RETRIES,
  1093. )
  1094. state.gates.append(gate)
  1095. self._save()
  1096. return gate
  1097. def remove_gate(self, index_1based: int) -> str:
  1098. """Remove a gate by 1-based index. Returns the removed command."""
  1099. return self._pop_item("gates", index_1based).command
  1100. def clear_gates(self) -> int:
  1101. """Remove all gates. Returns the previous count."""
  1102. return self._clear_items("gates")
  1103. def render_gates(self) -> str:
  1104. """Public helper for the /goal gate slash command."""
  1105. if self._state is None:
  1106. return "(no active goal)"
  1107. if not self._state.gates:
  1108. return "(no quality gates — use /goal gate add <command> to require one)"
  1109. lines = []
  1110. for i, g in enumerate(self._state.gates, start=1):
  1111. status = ""
  1112. if g.last_exit_code == 0:
  1113. status = " ✓ passing"
  1114. elif g.last_exit_code is not None:
  1115. status = f" ✗ failing (exit {g.last_exit_code}, attempt {g.attempts}/{g.max_retries})"
  1116. lines.append(f"- {i}. $ {g.command}{status}")
  1117. return "\n".join(lines)
  1118. def _check_gates(self) -> Optional[dict[str, Any]]:
  1119. """Run quality gates in order; return a decision dict on failure.
  1120. Every eligible boundary re-executes a failed gate. A git HEAD+porcelain fingerprint used to
  1121. replay the recorded failure when "nothing changed", but porcelain sees neither the contents
  1122. of an untracked or already-modified file nor inputs outside the repo, so a repaired input
  1123. was replayed as still-failing until retry exhaustion paused the goal (#110649). The
  1124. retry cap below still bounds a genuinely stuck red suite.
  1125. """
  1126. state = self._state
  1127. if state is None or not state.gates:
  1128. return None
  1129. gate_cwd, refusal = _gate_workspace()
  1130. if refusal:
  1131. return self._pause_decision(
  1132. f"quality gates not run: {refusal}", "gate_failed", f"gates not run: {refusal}",
  1133. f"⏸ Goal paused — quality gates not run: {refusal}. Fix the workspace or "
  1134. f"/goal gate remove the gates, then /goal resume.",
  1135. )
  1136. for gate in state.gates:
  1137. passed, exit_code, tail = run_gate(gate, cwd=gate_cwd)
  1138. gate.last_exit_code = exit_code
  1139. gate.last_output_tail = tail
  1140. if passed:
  1141. gate.attempts = 0
  1142. continue
  1143. gate.attempts += 1
  1144. if gate.attempts > gate.max_retries:
  1145. return self._pause_decision(
  1146. f"quality gate exhausted {gate.attempts - 1} retries: $ {gate.command}",
  1147. "gate_failed", f"gate exhausted retries: $ {gate.command}",
  1148. f"⏸ Goal paused — quality gate still failing after "
  1149. f"{gate.max_retries} retries: $ {gate.command} "
  1150. f"(exit {exit_code}). Fix it manually or /goal gate remove it, "
  1151. f"then /goal resume.",
  1152. )
  1153. self._save()
  1154. prompt = CONTINUATION_PROMPT_GATE_FAILED_TEMPLATE.format(
  1155. goal=state.goal, command=gate.command, exit_code=exit_code, attempt=gate.attempts,
  1156. max_retries=gate.max_retries, output=tail or "(no output)",
  1157. )
  1158. return _decision(
  1159. "active", True, prompt, "gate_failed",
  1160. f"gate failed (exit {exit_code}): $ {gate.command}",
  1161. f"✗ Quality gate failed ({state.turns_used}/{state.max_turns} turns, "
  1162. f"attempt {gate.attempts}/{gate.max_retries}): $ {gate.command}",
  1163. )
  1164. self._save()
  1165. return None
  1166. # --- /goal wait barrier -------------------------------------------
  1167. def _park(self, reason: str, **barrier) -> GoalState:
  1168. state = self._require_active()
  1169. state.clear_wait()
  1170. for k, v in barrier.items():
  1171. setattr(state, k, v)
  1172. state.waiting_reason = (reason or "").strip() or None
  1173. state.waiting_since = time.time()
  1174. return self._save()
  1175. def wait_on(self, pid: int, reason: str = "") -> GoalState:
  1176. """Park the goal loop until a background PID exits (no turn burned, no judge call). For a
  1177. process with a watch/notify trigger prefer ``wait_on_session``. Requires an active goal."""
  1178. self._require_active()
  1179. pid = int(pid)
  1180. if pid <= 0:
  1181. raise ValueError("pid must be a positive integer")
  1182. if not _pid_alive(pid):
  1183. raise ValueError("pid is not alive on this host")
  1184. return self._park(reason, waiting_on_pid=pid)
  1185. def wait_on_session(self, session_id: str, reason: str = "") -> GoalState:
  1186. """Park on a process_registry session's OWN trigger: exit OR ``watch_patterns`` match. The
  1187. right barrier for a long-lived watcher/poller that signals mid-run and may never exit."""
  1188. self._require_active()
  1189. session_id = str(session_id or "").strip()
  1190. if not session_id:
  1191. raise ValueError("session_id must be a non-empty string")
  1192. return self._park(reason, waiting_on_session=session_id)
  1193. def wait_for_seconds(self, seconds: int, reason: str = "", *, on_delegations: int = 0) -> GoalState:
  1194. """Park until ``seconds`` from now (backoff/cooldown waits with no process to track). With
  1195. ``on_delegations`` the wait is FOR those live delegation batches: it also lifts as soon as
  1196. fewer are live (a batch result came back), so the loop re-judges with the result in hand
  1197. instead of sleeping out a 20-minute timer (independent review: results arrived with 1,199 s
  1198. left on the timer and nothing re-judged)."""
  1199. self._require_active()
  1200. seconds = int(seconds)
  1201. if seconds <= 0:
  1202. raise ValueError("seconds must be a positive integer")
  1203. return self._park(reason, waiting_until=time.time() + seconds, waiting_on_delegations=max(0, int(on_delegations)))
  1204. def stop_waiting(self) -> bool:
  1205. """Clear any active wait barrier (pid / session / time). Returns True if one was cleared."""
  1206. s = self._state
  1207. if s is None or (s.waiting_on_pid is None and s.waiting_on_session is None and not s.waiting_until):
  1208. return False
  1209. s.clear_wait()
  1210. self._save()
  1211. return True
  1212. def is_waiting(self) -> bool:
  1213. """True iff a barrier is set AND not yet satisfied. A satisfied barrier is cleared here
  1214. (lazy auto-clear) so the next evaluation resumes normal judging. A pid/session barrier
  1215. also expires after ``_MAX_BARRIER_WAIT_S``: a watcher or poller that never exits would
  1216. otherwise park the goal indefinitely (one run sat 3 h 22 min on a poller that outlived
  1217. the work it was polling)."""
  1218. s = self._state
  1219. if s is None:
  1220. return False
  1221. if s.waiting_on_session is not None:
  1222. still = _session_waiting(s.waiting_on_session)
  1223. elif s.waiting_on_pid is not None:
  1224. still = _pid_alive(s.waiting_on_pid)
  1225. elif s.waiting_until:
  1226. still = time.time() < s.waiting_until
  1227. if still and s.waiting_on_delegations > 0:
  1228. # Set because of live delegations: lift the moment one of them returned.
  1229. live = count_active_delegations(self.session_id)
  1230. if live < s.waiting_on_delegations:
  1231. still = False
  1232. else:
  1233. return False
  1234. if still and s.waiting_since and s.waiting_until == 0.0 and time.time() - s.waiting_since > _MAX_BARRIER_WAIT_S:
  1235. logger.info("goal %s: wait barrier on %s exceeded %ds; resuming judging",
  1236. self.session_id, s.waiting_on_session or s.waiting_on_pid, _MAX_BARRIER_WAIT_S)
  1237. still = False
  1238. if not still:
  1239. self.stop_waiting()
  1240. return still
  1241. # --- the main entry point called after every turn -----------------
  1242. def _waiting_decision(self, state: GoalState) -> dict[str, Any]:
  1243. if state.waiting_on_session is not None:
  1244. tgt = f"session {state.waiting_on_session}"
  1245. elif state.waiting_on_pid is not None:
  1246. tgt = f"pid {state.waiting_on_pid}"
  1247. else:
  1248. tgt = f"{max(0, int(state.waiting_until - time.time()))}s remaining"
  1249. reason = state.waiting_reason or tgt
  1250. return _decision("active", False, None, "waiting", reason, f"⏳ Goal parked — waiting on {tgt}: {reason}")
  1251. def _apply_wait_directive(self, wait_directive: dict[str, Any], reason: str, *, active_delegations: int = 0) -> Optional[dict[str, Any]]:
  1252. """Judge said WAIT: set the barrier and park. The counted turn stands (the judge ran) but no
  1253. continuation fires; the loop resumes once the barrier clears. ``None`` = the barrier is
  1254. unobservable here, so the caller continues instead."""
  1255. if wait_directive.get("session_id"):
  1256. tgt = f"session {self.wait_on_session(str(wait_directive['session_id']), reason=reason).waiting_on_session}"
  1257. elif wait_directive.get("pid"):
  1258. pid = int(wait_directive["pid"])
  1259. try:
  1260. tgt = f"pid {self.wait_on(pid, reason=reason).waiting_on_pid}"
  1261. except ValueError:
  1262. # A remote or already-exited pid is a barrier this host can never observe lifting
  1263. # (#110826): the judge sees the same pid next turn and would re-park forever.
  1264. # Catching wait_on's own liveness check (rather than probing first) closes the
  1265. # window where the pid exits between a pre-check and the park.
  1266. logger.info("goal judge: wait_on_pid %s is not alive on this host; continuing", pid)
  1267. return None
  1268. else:
  1269. self.wait_for_seconds(int(wait_directive["seconds"]), reason=reason, on_delegations=active_delegations)
  1270. tgt = f"{wait_directive['seconds']}s"
  1271. return _decision("active", False, None, "wait", reason, f"⏳ Goal parked (judge) — waiting on {tgt}: {reason}")
  1272. def _budget_pause(self, state: GoalState, verdict: str, reason: str, note: str = "") -> dict[str, Any]:
  1273. return self._pause_decision(
  1274. f"turn budget exhausted ({state.turns_used}/{state.max_turns})", verdict, reason,
  1275. f"⏸ Goal paused — {state.turns_used}/{state.max_turns} turns used{note}. "
  1276. "Use /goal resume to keep going, or /goal clear to stop.",
  1277. )
  1278. def evaluate_after_turn(
  1279. self, last_response: str, *, user_initiated: bool = True,
  1280. background_processes: Optional[list[dict[str, Any]]] = None,
  1281. active_delegations: int = 0,
  1282. ) -> dict[str, Any]:
  1283. """Run gates + judge and update state. Return a decision dict (``status``, ``should_continue``,
  1284. ``continuation_prompt``, ``verdict``, ``reason``, ``message``). Both real user prompts and our
  1285. own continuations increment ``turns_used`` — both consume model budget."""
  1286. state = self._state
  1287. if state is None or state.status != "active":
  1288. return _decision(state.status if state else None, False, None, "inactive", "no active goal", "")
  1289. # Parked on a live process or an unexpired deadline: quiesce without burning a turn.
  1290. if self.is_waiting():
  1291. return self._waiting_decision(state)
  1292. state.turns_used += 1
  1293. state.last_turn_at = time.time()
  1294. # Gates run BEFORE the judge: a failing gate is deterministic evidence the goal is not done,
  1295. # so the judge is skipped and the gate's output drives the next turn (same turn budget).
  1296. gate_decision = self._check_gates()
  1297. if gate_decision is not None:
  1298. if gate_decision.get("should_continue") and state.turns_used >= state.max_turns:
  1299. return self._budget_pause(state, "gate_failed", gate_decision.get("reason", ""), note=" (a quality gate is still failing)")
  1300. return gate_decision
  1301. verdict, reason, parse_failed, wait_directive, transport_failed = judge_goal(
  1302. state.goal, last_response, subgoals=state.subgoals or None, background_processes=background_processes,
  1303. contract=state.contract if state.has_contract() else None, active_delegations=active_delegations,
  1304. )
  1305. state.last_verdict = verdict
  1306. state.last_reason = reason
  1307. # Parse failures reset on any usable reply INCLUDING transport errors, so a flaky network
  1308. # doesn't trip the auto-pause meant for bad judge models; transport failures are counted
  1309. # separately because persistent API errors (401, DNS) mean a broken config.
  1310. state.consecutive_parse_failures = state.consecutive_parse_failures + 1 if parse_failed else 0
  1311. state.consecutive_transport_failures = state.consecutive_transport_failures + 1 if transport_failed else 0
  1312. if verdict == "wait" and wait_directive:
  1313. parked = self._apply_wait_directive(wait_directive, reason, active_delegations=active_delegations)
  1314. if parked is not None:
  1315. return parked
  1316. # BLOCKED is NOT done: pause so the user sees the judge's reason and can re-scope or override,
  1317. # instead of burning turns on an unachievable goal or waving it through as complete.
  1318. # BLOCKED verdict: the judge ruled the goal genuinely cannot be satisfied as stated (impossible, out
  1319. # of scope, needs user input). See #100954.
  1320. if verdict == "blocked":
  1321. return self._pause_decision(
  1322. f"judged unachievable: {reason}", "blocked", reason,
  1323. f"🚫 Goal judged unachievable — paused: {reason} Re-scope with /goal set, or override with /goal resume.",
  1324. )
  1325. if verdict == "done":
  1326. state.status = "done"
  1327. self._save()
  1328. return _decision("done", False, None, "done", reason, f"✓ Goal achieved: {reason}")
  1329. # Persistent judge failures (API unreachable / unparseable output) auto-pause and point at the
  1330. # goal_judge config so a broken judge can't burn the whole turn budget.
  1331. n_tx, n_parse = state.consecutive_transport_failures, state.consecutive_parse_failures
  1332. if n_tx >= DEFAULT_MAX_CONSECUTIVE_TRANSPORT_FAILURES:
  1333. return self._pause_decision(
  1334. f"judge API unreachable {n_tx} turns in a row (check auxiliary.goal_judge provider/key in config.yaml)",
  1335. "continue", reason,
  1336. f"⏸ Goal paused — judge API returned errors ({n_tx} turns). Check the goal_judge provider/key in "
  1337. + _JUDGE_CONFIG_HINT.format(provider="deepseek", model="deepseek-flash"),
  1338. )
  1339. if n_parse >= DEFAULT_MAX_CONSECUTIVE_PARSE_FAILURES:
  1340. return self._pause_decision(
  1341. f"judge model returned unparseable output {n_parse} turns in a row", "continue", reason,
  1342. f"⏸ Goal paused — the judge model ({n_parse} turns) isn't returning the required JSON verdict. "
  1343. "Route the judge to a stricter model in "
  1344. + _JUDGE_CONFIG_HINT.format(provider="openrouter", model="google/gemini-3-flash-preview"),
  1345. )
  1346. if state.turns_used >= state.max_turns:
  1347. return self._budget_pause(state, "continue", reason)
  1348. self._save()
  1349. return _decision(
  1350. "active", True, self.next_continuation_prompt(), "continue", reason,
  1351. f"↻ Continuing toward goal ({state.turns_used}/{state.max_turns}): {reason}",
  1352. )
  1353. def next_continuation_prompt(self) -> Optional[str]:
  1354. s = self._state
  1355. if not s or s.status != "active":
  1356. return None
  1357. # Contract first (it carries the verification surface); subgoals fold in as extra criteria.
  1358. if s.has_contract():
  1359. contract_block = s.contract.render_block()
  1360. if s.subgoals:
  1361. contract_block = f"{contract_block}\n{_render_extra_criteria(s.subgoals)}"
  1362. return CONTINUATION_PROMPT_WITH_CONTRACT_TEMPLATE.format(goal=s.goal, contract_block=contract_block)
  1363. if s.subgoals:
  1364. return CONTINUATION_PROMPT_WITH_SUBGOALS_TEMPLATE.format(goal=s.goal, subgoals_block=s.render_subgoals_block())
  1365. return CONTINUATION_PROMPT_TEMPLATE.format(goal=s.goal)
  1366. def render_contract(self) -> str:
  1367. """Public helper for the /goal show + /goal draft slash commands."""
  1368. if self._state is None:
  1369. return "(no active goal)"
  1370. return self._state.contract.render_block() if self._state.has_contract() else (
  1371. "(no completion contract — set one with /goal draft <objective> or inline field: value lines)")
  1372. # ── Kanban worker goal loop ───────────────────────────────────────────
  1373. # Fed to a kanban goal-mode worker that hasn't completed/blocked its task yet: short, and points it
  1374. # back at the lifecycle contract (it already has the full task body).
  1375. KANBAN_GOAL_CONTINUATION_TEMPLATE = (
  1376. "[Continuing toward this kanban task — judge says it is not done yet]\n"
  1377. "Reason: {reason}\n\n"
  1378. "Take the next concrete step toward completing the task. When the work "
  1379. "is genuinely finished, call kanban_complete with a summary. If it is a "
  1380. "code change that needs same-card review before counting as done, call "
  1381. "kanban_request_review with a summary instead. If you are blocked and "
  1382. "need human input, call kanban_block with a reason. Do not stop without "
  1383. "calling one of them."
  1384. )
  1385. # Judge says done but the worker never made a terminal board call
  1386. # (kanban_complete/kanban_request_review/kanban_block): one explicit nudge.
  1387. KANBAN_GOAL_FINALIZE_TEMPLATE = (
  1388. "[The work looks complete, but the task is still open]\n"
  1389. "Reason: {reason}\n\n"
  1390. "If the task is genuinely done, call kanban_complete now with a short "
  1391. "summary of what you did. If it is a code change awaiting same-card review, "
  1392. "call kanban_request_review with that summary instead. If something still "
  1393. "blocks completion, call kanban_block with the reason instead."
  1394. )
  1395. # Worker-driven terminal task statuses → loop outcome. The card's own acceptance criteria are the
  1396. # goal; the worker already has the full task body, so these outcomes stop the loop cleanly.
  1397. _KANBAN_TERMINAL_STATUSES = {
  1398. "done": ("completed_by_worker", "worker completed the task", "task {task_id} completed by worker after {turns} turn(s)"),
  1399. "blocked": ("blocked_by_worker", "worker blocked the task", "task {task_id} blocked by worker after {turns} turn(s)"),
  1400. # kanban_request_review is a legitimate terminator: implementation done, awaiting a reviewer.
  1401. "review": ("review_requested_by_worker", "worker requested review", "task {task_id} handed off for review by worker after {turns} turn(s)"),
  1402. "changes_requested": ("changes_requested_by_reviewer", "reviewer requested changes", "reviewer returned task {task_id} for changes after {turns} turn(s)"),
  1403. }
  1404. def run_kanban_goal_loop(
  1405. *,
  1406. task_id: str,
  1407. goal_text: str,
  1408. run_turn,
  1409. task_status_fn,
  1410. block_fn,
  1411. max_turns: int = DEFAULT_MAX_TURNS,
  1412. first_response: str = "",
  1413. log=None,
  1414. ) -> dict[str, Any]:
  1415. """Drive a kanban worker through a Ralph-style goal loop.
  1416. Each iteration: stop if the worker already terminated the task (``kanban_complete`` /
  1417. ``kanban_block`` / review hand-off); otherwise judge the latest response against ``goal_text``
  1418. (the card's title + body) and feed a continuation or finalize nudge. A WAIT verdict is treated
  1419. as CONTINUE (workers finish via kanban tools, not by parking).
  1420. """
  1421. def _log(msg: str) -> None:
  1422. if log is not None:
  1423. try:
  1424. log(msg)
  1425. except Exception:
  1426. pass
  1427. def _block(message: str) -> None:
  1428. try:
  1429. block_fn(message)
  1430. except Exception as exc:
  1431. _log(f"kanban goal loop: block_fn failed ({exc})")
  1432. def _result(outcome: str, reason: str) -> dict[str, Any]:
  1433. return {"outcome": outcome, "turns_used": turns_used, "reason": reason}
  1434. max_turns = int(max_turns or DEFAULT_MAX_TURNS)
  1435. if max_turns < 1:
  1436. max_turns = DEFAULT_MAX_TURNS
  1437. last_response = first_response or ""
  1438. turns_used = 1 # the first turn already consumed one unit of budget
  1439. nudged_to_finalize = False
  1440. while True:
  1441. try:
  1442. status = task_status_fn()
  1443. except Exception as exc:
  1444. _log(f"kanban goal loop: status check failed ({exc}); stopping")
  1445. return _result("stopped", "status check failed")
  1446. terminal = _KANBAN_TERMINAL_STATUSES.get(status)
  1447. if terminal is not None:
  1448. outcome, reason, log_fmt = terminal
  1449. _log("kanban goal loop: " + log_fmt.format(task_id=task_id, turns=turns_used))
  1450. return _result(outcome, reason)
  1451. if status not in ("running", "ready"):
  1452. # Reclaimed / archived / unexpected — let the dispatcher own it.
  1453. _log(f"kanban goal loop: task {task_id} status={status!r}; stopping")
  1454. return _result("stopped", f"status={status}")
  1455. from agent.portal_tags import get_affinity_scope, reset_affinity_scope, set_affinity_scope
  1456. affinity_token = None if get_affinity_scope() else set_affinity_scope(f"kanban:{task_id}")
  1457. try:
  1458. verdict, reason, _parse_failed, _wait, _transport_failed = judge_goal(goal_text, last_response)
  1459. finally:
  1460. if affinity_token is not None:
  1461. reset_affinity_scope(affinity_token)
  1462. if _transport_failed:
  1463. _log(f"kanban goal loop: judge transport failed on turn {turns_used}; stopping")
  1464. return _result("stopped", "judge transport failure")
  1465. if verdict == "wait":
  1466. verdict = "continue"
  1467. _log(f"kanban goal loop: turn {turns_used}/{max_turns} verdict={verdict} reason={_truncate(reason, 120)}")
  1468. if verdict == "blocked":
  1469. # Unachievable is NOT done: block the card with the judge's reason now instead of
  1470. # re-poking an impossible goal, and never let it land in done.
  1471. # The judge ruled the goal cannot be satisfied at all — this is NOT done (#100954).
  1472. _log(f"kanban goal loop: task {task_id} judged unachievable; blocking")
  1473. _block(f"Goal-mode judge ruled the goal unachievable: {reason}")
  1474. return _result("blocked_unachievable", f"judge verdict blocked: {reason}")
  1475. if verdict == "done":
  1476. if nudged_to_finalize:
  1477. # Already asked once to call kanban_complete — block for review rather than spin.
  1478. _log(f"kanban goal loop: task {task_id} judged done but worker won't finalize; blocking")
  1479. _block(
  1480. f"Goal-mode worker's output looked complete but it never "
  1481. f"called kanban_complete after a finalize nudge ({reason})."
  1482. )
  1483. return _result("blocked_budget", "judged done, never finalized")
  1484. prompt = KANBAN_GOAL_FINALIZE_TEMPLATE.format(reason=_truncate(reason, 400))
  1485. nudged_to_finalize = True
  1486. else:
  1487. prompt = KANBAN_GOAL_CONTINUATION_TEMPLATE.format(reason=_truncate(reason, 400))
  1488. # Budget check BEFORE spending another turn.
  1489. if turns_used >= max_turns:
  1490. _log(f"kanban goal loop: task {task_id} exhausted {turns_used}/{max_turns} turns; blocking")
  1491. _block(
  1492. f"Goal-mode worker exhausted its turn budget "
  1493. f"({turns_used}/{max_turns}) without completing the task. "
  1494. f"Last judge verdict: {_truncate(reason, 300)}"
  1495. )
  1496. return _result("blocked_budget", "turn budget exhausted")
  1497. try:
  1498. result = run_turn(prompt)
  1499. if isinstance(result, dict):
  1500. last_response = result.get("response", "") or ""
  1501. failed = bool(result.get("failed", False))
  1502. failure_reason = result.get("failure_reason") or "unknown"
  1503. else:
  1504. # backward compatibility: assume it's a string
  1505. last_response = result or ""
  1506. failed = False
  1507. failure_reason = None
  1508. except Exception as exc:
  1509. _log(f"kanban goal loop: run_turn failed ({exc}); stopping")
  1510. return _result("stopped", f"run_turn error: {type(exc).__name__}")
  1511. if failed:
  1512. _log(f"kanban goal loop: worker failed on turn {turns_used} (reason={failure_reason}); stopping")
  1513. return _result("stopped", f"worker failed: {failure_reason}")
  1514. turns_used += 1
  1515. __all__ = [
  1516. "CONTINUATION_PROMPT_TEMPLATE",
  1517. "CONTINUATION_PROMPT_WITH_CONTRACT_TEMPLATE",
  1518. "CONTINUATION_PROMPT_WITH_SUBGOALS_TEMPLATE",
  1519. "DEFAULT_MAX_TURNS",
  1520. "DRAFT_CONTRACT_SYSTEM_PROMPT",
  1521. "JUDGE_USER_PROMPT_TEMPLATE",
  1522. "JUDGE_USER_PROMPT_WITH_CONTRACT_TEMPLATE",
  1523. "JUDGE_USER_PROMPT_WITH_SUBGOALS_TEMPLATE",
  1524. "KANBAN_GOAL_CONTINUATION_TEMPLATE",
  1525. "KANBAN_GOAL_FINALIZE_TEMPLATE",
  1526. "GoalContract",
  1527. "GoalGate",
  1528. "GoalManager",
  1529. "GoalState",
  1530. "clear_goal",
  1531. "draft_contract",
  1532. "judge_goal",
  1533. "load_goal",
  1534. "migrate_goal_to_session",
  1535. "parse_contract",
  1536. "run_gate",
  1537. "run_kanban_goal_loop",
  1538. "save_goal",
  1539. ]