oneshot.py 31 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665
  1. """Oneshot (-z) mode: send a prompt, get the final content block, exit.
  2. Toolsets = explicit --toolsets, else the user's "cli" toolsets from `hermes tools`. Rules /
  3. memory / AGENTS.md / preloaded skills = same as a normal chat turn. Approvals are auto-bypassed
  4. (HERMES_YOLO_MODE=1). Model/provider mirror `hermes chat`: both optional; only --model → auto-detect
  5. the provider; only --provider → error (ambiguous).
  6. """
  7. from __future__ import annotations
  8. import json
  9. import logging
  10. import os
  11. import sys
  12. from contextlib import redirect_stderr, redirect_stdout
  13. import dataclasses
  14. from dataclasses import dataclass
  15. from pathlib import Path
  16. from typing import Optional
  17. from gateway.session_context import declare_stateless_channel
  18. from hermes_cli.fallback_config import get_fallback_chain
  19. _ALL_TOOLSETS = {"all", "*"}
  20. # Keys copied from the run result into the ``--usage-file`` report. ``service_tier`` is a
  21. # billing-audit field: the tier REQUESTED via request_overrides.extra_body (None when unset), so
  22. # batch pipelines can verify the tier they pay for went out on the wire. ``partial`` /
  23. # ``interrupted`` / ``turn_exit_reason`` say WHY ``completed`` is false, so a pipeline can tell
  24. # an iteration-budget stop from a Ctrl-C without parsing stderr (#111770).
  25. _USAGE_KEYS = (
  26. "estimated_cost_usd", "cost_status", "cost_source", "input_tokens", "output_tokens",
  27. "cache_read_tokens", "cache_write_tokens", "reasoning_tokens", "total_tokens", "api_calls",
  28. "model", "provider", "session_id", "completed", "partial", "interrupted", "turn_exit_reason",
  29. )
  30. # Counters summed per auxiliary task (vision, compression, title_generation, ...) into the
  31. # ``auxiliary`` block of the report. The main-loop keys above stay main-loop-only (backward
  32. # compatible); ``total_including_auxiliary`` carries the grand total pipelines bill on (#112848).
  33. _AUX_COUNTERS = (
  34. "api_calls", "input_tokens", "output_tokens", "cache_read_tokens", "cache_write_tokens",
  35. "reasoning_tokens", "estimated_cost_usd",
  36. )
  37. def _auxiliary_usage(session_db, session_id: Optional[str]) -> dict[str, dict]:
  38. """Per-task aux usage recorded for *session_id*'s lineage (``{}`` without a store / session)."""
  39. if session_db is None or not session_id:
  40. return {}
  41. try:
  42. return session_db.auxiliary_usage_by_task(session_id)
  43. except Exception:
  44. logging.debug("oneshot: auxiliary usage read failed", exc_info=True)
  45. return {}
  46. def _attach_auxiliary_usage(result: dict, session_db, before: dict[str, dict],
  47. fallback_session_id: Optional[str] = None) -> None:
  48. """Store this run's auxiliary usage on *result* as the delta against the pre-turn snapshot
  49. (a resumed session already carries earlier runs' aux rows). Waits (bounded) for the auto-title
  50. thread first: it bills from a daemon thread and can still be in flight when the turn returns.
  51. Failed-turn dicts carry no ``session_id``; *fallback_session_id* keeps the delta readable then."""
  52. from agent.title_generator import wait_for_title_upgrades
  53. wait_for_title_upgrades()
  54. after = _auxiliary_usage(session_db, result.get("session_id") or fallback_session_id)
  55. by_task: dict[str, dict] = {}
  56. for task, counters in after.items():
  57. prior = before.get(task, {})
  58. delta = {key: (counters.get(key) or 0) - (prior.get(key) or 0) for key in _AUX_COUNTERS}
  59. if any(delta.values()):
  60. by_task[task] = delta
  61. result["auxiliary_usage"] = by_task
  62. def _auxiliary_report(report: dict, by_task: dict[str, dict]) -> None:
  63. """Add the ``auxiliary`` breakdown and ``total_including_auxiliary`` to the ledger."""
  64. totals = {key: sum(t.get(key) or 0 for t in by_task.values()) for key in _AUX_COUNTERS}
  65. totals["total_tokens"] = totals["input_tokens"] + totals["output_tokens"]
  66. report["auxiliary"] = {**totals, "by_task": by_task}
  67. main_cost = report.get("estimated_cost_usd")
  68. report["total_including_auxiliary"] = {
  69. "estimated_cost_usd": None if main_cost is None else main_cost + totals["estimated_cost_usd"],
  70. "total_tokens": (report.get("total_tokens") or 0) + totals["total_tokens"],
  71. "api_calls": (report.get("api_calls") or 0) + totals["api_calls"],
  72. }
  73. # Exit code for a turn stopped by an interrupt (SIGINT convention, same as ``chat -Q``).
  74. _INTERRUPTED_EXIT_CODE = 130
  75. def _oneshot_exit_code(response: Optional[str], result: dict) -> int:
  76. """Map a finished ``-z`` turn onto its exit code: ``0`` only when the turn completed;
  77. ``130`` interrupted; ``2`` failed or stopped partway (``partial``, ``completed: False`` such
  78. as the iteration budget); ``1`` a completed turn that produced no text at all.
  79. The outcome is judged from the result, not from whether text was printed: a partial or
  80. failed turn usually leaves an explanation on stdout, and exiting 0 for it made scripts treat
  81. a half-done job (or a provider error summary) as success (#111770).
  82. """
  83. if result.get("interrupted"):
  84. return _INTERRUPTED_EXIT_CODE
  85. if result.get("failed") or result.get("partial") or result.get("completed") is False:
  86. return 2
  87. if not (response or "").strip():
  88. return 1
  89. return 0
  90. def _normalize_toolsets(toolsets: object = None) -> list[str] | None:
  91. """Split repeated/comma-separated toolset flags into a clean list (``None`` when empty)."""
  92. if not toolsets:
  93. return None
  94. items = toolsets if isinstance(toolsets, (list, tuple)) else [toolsets]
  95. parts = [str(item).split(",") if isinstance(item, str) else [str(item)] for item in items]
  96. return [p.strip() for chunk in parts for p in chunk if p.strip()] or None
  97. def _normalize_skills(skills: object = None) -> list[str]:
  98. """Normalize repeated/comma-separated skill flags and preserve order."""
  99. return list(dict.fromkeys(_normalize_toolsets(skills) or []))
  100. def _build_preloaded_skills_prompt(skills: object = None) -> str | None:
  101. """Load requested skills using the same partial-success contract as CLI chat."""
  102. parsed_skills = _normalize_skills(skills)
  103. if not parsed_skills:
  104. return None
  105. from agent.skill_commands import build_preloaded_skills_prompt, format_missing_skills
  106. skills_prompt, loaded_skills, missing_skills = build_preloaded_skills_prompt(parsed_skills)
  107. if missing_skills:
  108. if not loaded_skills:
  109. raise ValueError(format_missing_skills(missing_skills))
  110. logging.warning(
  111. "Skipping %s. Continuing with: %s. List available skills with `hermes skills list`.",
  112. format_missing_skills(missing_skills),
  113. ", ".join(loaded_skills),
  114. )
  115. return skills_prompt or None
  116. def _configured_mcp_servers() -> tuple[set[str], set[str]]:
  117. """``(enabled, disabled)`` MCP server names from config; both empty on any error."""
  118. try:
  119. from hermes_cli.config import read_raw_config
  120. from tools.mcp_tool_common import mcp_server_enabled
  121. cfg = read_raw_config()
  122. mcp_servers = cfg.get("mcp_servers") if isinstance(cfg.get("mcp_servers"), dict) else {}
  123. enabled: set[str] = set()
  124. disabled: set[str] = set()
  125. for name, server_cfg in mcp_servers.items():
  126. if not isinstance(server_cfg, dict):
  127. continue
  128. target = enabled if mcp_server_enabled(server_cfg) else disabled
  129. target.add(str(name))
  130. return enabled, disabled
  131. except Exception:
  132. return set(), set()
  133. def _validate_explicit_toolsets(toolsets: object = None) -> tuple[list[str] | None, str | None]:
  134. normalized = _normalize_toolsets(toolsets)
  135. if normalized is None:
  136. return None, None
  137. try:
  138. from toolsets import validate_toolset
  139. except Exception as exc:
  140. return None, f"hermes -z: failed to validate --toolsets: {exc}\n"
  141. built_in = [name for name in normalized if validate_toolset(name)]
  142. unresolved = [name for name in normalized if name not in built_in]
  143. if unresolved:
  144. try:
  145. from hermes_cli.plugins import discover_plugins
  146. discover_plugins()
  147. plugin_valid = [name for name in unresolved if validate_toolset(name)]
  148. except Exception:
  149. plugin_valid = []
  150. built_in.extend(plugin_valid)
  151. unresolved = [name for name in unresolved if name not in plugin_valid]
  152. if any(name in _ALL_TOOLSETS for name in built_in):
  153. ignored = [name for name in normalized if name not in _ALL_TOOLSETS]
  154. if ignored:
  155. sys.stderr.write(
  156. "hermes -z: --toolsets all enables every toolset; "
  157. f"ignoring additional entries: {', '.join(ignored)}\n"
  158. )
  159. return None, None
  160. mcp_names, mcp_disabled = _configured_mcp_servers() if unresolved else (set(), set())
  161. mcp_valid = [name for name in unresolved if name in mcp_names]
  162. disabled = [name for name in unresolved if name in mcp_disabled]
  163. unknown = [name for name in unresolved if name not in mcp_names and name not in mcp_disabled]
  164. valid = built_in + mcp_valid
  165. if unknown:
  166. sys.stderr.write(f"hermes -z: ignoring unknown --toolsets entries: {', '.join(unknown)}\n")
  167. if disabled:
  168. sys.stderr.write(
  169. "hermes -z: ignoring disabled MCP servers (set enabled: true in config.yaml to use): "
  170. f"{', '.join(disabled)}\n"
  171. )
  172. if not valid:
  173. return None, "hermes -z: --toolsets did not contain any valid toolsets.\n"
  174. return valid, None
  175. def _write_usage_file(path: Optional[str], result: dict, failure: Optional[str] = None) -> None:
  176. """Best-effort JSON usage report for pipelines (``-z --usage-file``).
  177. Written even on failure so callers can always account for spend. Never raises — a broken usage
  178. write must not mask the run's own outcome.
  179. """
  180. if not path:
  181. return
  182. try:
  183. report = {key: result.get(key) for key in _USAGE_KEYS}
  184. report["failed"] = bool(result.get("failed")) or failure is not None
  185. report["service_tier"] = result.get("service_tier")
  186. if isinstance(result.get("auxiliary_usage"), dict):
  187. _auxiliary_report(report, result["auxiliary_usage"])
  188. if failure is not None:
  189. report["failure"] = failure
  190. out = Path(path).expanduser()
  191. out.parent.mkdir(parents=True, exist_ok=True)
  192. out.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
  193. except Exception:
  194. pass
  195. def run_oneshot(
  196. prompt: str,
  197. model: Optional[str] = None,
  198. provider: Optional[str] = None,
  199. toolsets: object = None,
  200. skills: object = None,
  201. usage_file: Optional[str] = None,
  202. resume: Optional[str] = None,
  203. reasoning: object = None,
  204. ) -> int:
  205. """Execute a single prompt and print only the final content block.
  206. Model/provider fall back to ``HERMES_INFERENCE_MODEL`` and config.yaml. ``usage_file`` gets a
  207. JSON usage report even when the run fails. ``resume`` is a session id (already normalized by
  208. the CLI layer: latest/title/--continue resolution) whose transcript is loaded and continued
  209. by this turn. Returns the exit code; the caller owns process termination.
  210. """
  211. # Silence every stdlib logger: AIAgent, tools and provider adapters log to stderr through the
  212. # root logger. File handlers from setup_logging() keep working (level-independent).
  213. logging.disable(logging.CRITICAL)
  214. # --provider without --model is ambiguous (the provider may not host the configured model, and
  215. # picking its catalog default hides the mismatch). Validate BEFORE the stderr redirect.
  216. env_model_early = os.getenv("HERMES_INFERENCE_MODEL", "").strip()
  217. if provider and not ((model or "").strip() or env_model_early):
  218. sys.stderr.write(
  219. "hermes -z: --provider requires --model (or HERMES_INFERENCE_MODEL). "
  220. "Pass both explicitly, or neither to use your configured defaults.\n"
  221. )
  222. return 2
  223. explicit_toolsets, toolsets_error = _validate_explicit_toolsets(toolsets)
  224. if toolsets_error:
  225. sys.stderr.write(toolsets_error)
  226. return 2
  227. use_config_toolsets = _normalize_toolsets(toolsets) is None
  228. # Non-interactive by definition — an approval prompt would hang forever.
  229. os.environ["HERMES_YOLO_MODE"] = "1"
  230. os.environ["HERMES_ACCEPT_HOOKS"] = "1"
  231. # Same finite-chat marker as `hermes chat -q` (cli.py): the session-source resolver uses it to drop an
  232. # inherited tui/desktop transport label, and delegate dispatch to route detached results inline.
  233. os.environ["HERMES_SINGLE_QUERY_SESSION"] = "1"
  234. # Nothing here drains process_registry.completion_queue (only cli.py's process_loop and the
  235. # gateway watchers do), so left unbound delegate_task would be forced background and every
  236. # subagent result discarded. Stateless routes it to the inline/synchronous path.
  237. declare_stateless_channel()
  238. # Redirect stderr AND stdout for the entire call tree; the final response goes to the real
  239. # stdout at the end.
  240. real_stdout = sys.stdout
  241. real_stderr = sys.stderr
  242. response: Optional[str] = None
  243. result: dict = {}
  244. failure: BaseException | None = None
  245. with open(os.devnull, "w", encoding="utf-8") as devnull, redirect_stdout(devnull), redirect_stderr(devnull):
  246. try:
  247. response, result = _run_agent(
  248. prompt,
  249. model=model,
  250. provider=provider,
  251. toolsets=explicit_toolsets,
  252. use_config_toolsets=use_config_toolsets,
  253. skills=skills,
  254. resume=resume,
  255. reasoning=reasoning,
  256. ledger=bool(usage_file),
  257. )
  258. except BaseException as exc:
  259. # Capture anything escaping the agent (OSError from prompt_toolkit on a non-TTY pipe,
  260. # KeyboardInterrupt, SystemExit, ...) so it reaches the real stderr instead of dying
  261. # silently past the redirect — the worst failure mode in cron / SSH / subprocess use.
  262. failure = exc
  263. if failure is not None:
  264. # Control-flow exceptions (Ctrl-C / sys.exit inside the agent) re-raise to the parent.
  265. if isinstance(failure, (KeyboardInterrupt, SystemExit)):
  266. _write_usage_file(usage_file, result, failure=repr(failure))
  267. raise failure
  268. _write_usage_file(usage_file, result, failure=str(failure))
  269. real_stderr.write(f"hermes -z: agent failed: {failure}\n")
  270. real_stderr.flush()
  271. return 1
  272. _write_usage_file(usage_file, result)
  273. if response:
  274. # Lone UTF-16 surrogates would raise UnicodeEncodeError on a real stdout and abort with
  275. # exit 1 after the turn already completed — scrub to U+FFFD first.
  276. # Model text can contain lone UTF-16 surrogates (invalid in UTF-8). See #80366.
  277. from agent.message_sanitization import _sanitize_surrogates
  278. response = _sanitize_surrogates(response)
  279. real_stdout.write(response)
  280. if not response.endswith("\n"):
  281. real_stdout.write("\n")
  282. real_stdout.flush()
  283. exit_code = _oneshot_exit_code(response, result)
  284. if exit_code == 1:
  285. real_stderr.write("hermes -z: no final response was produced; treating the run as failed.\n")
  286. real_stderr.flush()
  287. return exit_code
  288. def _create_session_db_for_oneshot():
  289. """Best-effort SessionDB — oneshot bypasses ``HermesCLI._init_agent()``, so it must wire the
  290. SQLite store itself or ``session_search`` is advertised but always unavailable. The registry
  291. handle is the one in-process tools (delegation, goals) acquire during the run, so the process
  292. holds one writer; ``_close_agent``'s ``close()`` releases the refcount."""
  293. try:
  294. from hermes_state_registry import acquire
  295. return acquire()
  296. except Exception as exc:
  297. logging.debug("SQLite session store not available for oneshot mode: %s", exc)
  298. return None
  299. @dataclass
  300. class _ModelChoice:
  301. model: str
  302. provider: str | None
  303. base_url: str | None = None
  304. api_key: str | None = None
  305. api_mode: str | None = None
  306. def _configured_model(model_cfg: object) -> str:
  307. if isinstance(model_cfg, str):
  308. return model_cfg
  309. raw = model_cfg.get("default") or model_cfg.get("model") or ""
  310. if isinstance(raw, dict):
  311. from hermes_cli.config import split_model_config_default
  312. return split_model_config_default(raw)[0]
  313. return str(raw or "")
  314. def _resolve_model_and_provider(cfg: dict, model: Optional[str], provider: Optional[str]) -> _ModelChoice:
  315. """Effective model = arg → env → config; provider = arg → auto-detect → config/env.
  316. Auto-detection only runs when the model was explicitly requested (arg or env var) — same
  317. semantic as ``/model <name>`` — because the configured default provider may not host it.
  318. Config-sourced models are the "use my defaults" path and keep the configured provider.
  319. """
  320. from hermes_cli.models import detect_provider_for_model
  321. model_cfg = cfg.get("model") or {}
  322. env_model = os.getenv("HERMES_INFERENCE_MODEL", "").strip()
  323. explicit_model = (model or "").strip() or env_model
  324. choice = _ModelChoice(explicit_model or _configured_model(model_cfg), (provider or "").strip() or None)
  325. if choice.provider is not None or not explicit_model:
  326. return choice
  327. # DIRECT_ALIASES (config.yaml ``model_aliases:``) map a user alias to (model, provider,
  328. # base_url) for endpoints outside any catalog (local servers, custom proxies, ...).
  329. from hermes_cli import model_switch as _ms
  330. try:
  331. _ms._ensure_direct_aliases()
  332. direct = _ms.DIRECT_ALIASES.get(explicit_model.strip().lower())
  333. except Exception:
  334. direct = None
  335. if direct is None:
  336. cfg_provider = ""
  337. if isinstance(model_cfg, dict):
  338. cfg_provider = str(model_cfg.get("provider") or "").strip().lower()
  339. current_provider = cfg_provider or os.getenv("HERMES_INFERENCE_PROVIDER", "").strip().lower() or "auto"
  340. # Same owner as HermesCLI startup: a provider-qualified string (``custom:<name>:<model>``,
  341. # ``<provider>/<model>``) selects that provider before auto-detection can hand the unsplit
  342. # string to the configured default (#73943).
  343. route = _ms.resolve_startup_model_route(
  344. explicit_model, current_provider=current_provider,
  345. user_providers=cfg.get("providers"), custom_providers=cfg.get("custom_providers"))
  346. if route is not None:
  347. choice.provider, choice.model = route.provider, route.model
  348. return choice
  349. detected = detect_provider_for_model(explicit_model, current_provider)
  350. if detected:
  351. choice.provider, choice.model = detected
  352. return choice
  353. choice.model = direct.model
  354. choice.provider = direct.provider
  355. # Resolve through the SAME owner the interactive `/model` path uses: passing `direct.provider`
  356. # with a URL-bearing alias would let a label like `anthropic` keep the alias's base_url yet
  357. # fall back to the live vendor token — a bearer credential crossing an origin boundary. The
  358. # helper forces bare `custom` for URL-bearing aliases and carries the alias's own key.
  359. try:
  360. choice.provider, choice.api_key = _ms.direct_alias_runtime_request(direct)
  361. except Exception:
  362. choice.api_key = None
  363. if direct.base_url:
  364. choice.base_url = direct.base_url.rstrip("/")
  365. return choice
  366. def _load_resume_target(session_db, resume: Optional[str]) -> tuple[Optional[str], list, Optional[dict]]:
  367. """Resolve ``resume`` to ``(session_id, conversation_history, session_meta)`` for a oneshot turn.
  368. Follows the same contract as the interactive CLI resume: compression-chain redirect via
  369. ``resolve_resume_session_id``, safe-resume guard, model-projection history with
  370. ``session_meta`` rows dropped. An unknown session raises (the user passed an explicit id;
  371. silently starting a fresh session is the resume-dropped failure mode this exists to fix —
  372. see #105892). An empty stored transcript still returns the resolved id: the turn replays
  373. nothing but is recorded under the requested session — ``hermes -z "hello" -c <title>
  374. --create-if-missing`` must fill the titled session it created, not mint a fresh id
  375. (same contract as the interactive /resume of an empty session).
  376. The resolved row is also reopened (best effort): the previous run stamped ``ended_at``,
  377. the existing-row upsert never clears the end fields, and ``end_session()`` only writes
  378. rows whose ``ended_at`` is null — so without this step the resumed turn would be recorded
  379. under a session that stays closed and its new lifecycle boundary would be lost (same
  380. reason the interactive resume calls ``reopen_session()`` before continuing).
  381. """
  382. if not resume:
  383. return None, [], None
  384. if session_db is None:
  385. raise RuntimeError(f"cannot resume session {resume}: session store unavailable")
  386. resolved = session_db.resolve_resume_session_id(resume) or resume
  387. session_meta = session_db.get_session(resolved)
  388. if not session_meta:
  389. raise RuntimeError(f"session not found: {resume}")
  390. # A Kanban worker transcript resumes only through a dispatcher-owned run (#68779): a
  391. # quiet one-shot resume would be a write-capable process the board cannot observe.
  392. from hermes_cli.kanban_resume_guard import kanban_resume_refusal
  393. if (kanban_refusal := kanban_resume_refusal(session_db, resolved)) is not None:
  394. raise RuntimeError(f"cannot resume session {resume}: {kanban_refusal}")
  395. session_db.assert_resume_safe(resolved, tip_only=True)
  396. restored, _display = session_db.get_resume_conversations(resolved)
  397. history = [m for m in restored if m.get("role") != "session_meta"]
  398. try:
  399. session_db.reopen_session(resolved)
  400. except Exception:
  401. logging.debug("reopen_session failed for resumed one-shot session %s", resolved, exc_info=True)
  402. return resolved, history, session_meta
  403. def _apply_stored_session_runtime(
  404. choice: _ModelChoice, session_meta: Optional[dict], *, explicit_model: bool,
  405. ) -> _ModelChoice:
  406. """Run a resumed one-shot on the session's stored runtime, not the ambient config — the same
  407. contract as the interactive ``_restore_session_model``, via the shared ``stored_session_route``.
  408. An explicit ``--model`` keeps the ambient choice. A changed provider drops the resolved
  409. ``api_key``: it belongs to the ambient endpoint and is never persisted, so runtime resolution
  410. re-fetches credentials for the restored provider."""
  411. if explicit_model:
  412. return choice
  413. from hermes_cli.cli_model_switch_mixin import stored_session_route
  414. route = stored_session_route(session_meta, current_model=choice.model, current_provider=choice.provider)
  415. if route is None:
  416. return choice
  417. choice.model, stored_provider, stored_base_url, stored_api_mode, provider_changed = route
  418. if provider_changed:
  419. choice.provider = stored_provider
  420. choice.base_url = stored_base_url
  421. choice.api_key = None
  422. if stored_api_mode:
  423. choice.api_mode = str(stored_api_mode)
  424. return choice
  425. def _run_agent(
  426. prompt: str,
  427. model: Optional[str] = None,
  428. provider: Optional[str] = None,
  429. toolsets: object = None,
  430. use_config_toolsets: bool = True,
  431. skills: object = None,
  432. resume: Optional[str] = None,
  433. reasoning: object = None,
  434. ledger: bool = False,
  435. ) -> tuple[str, dict]:
  436. """Build an AIAgent exactly like a normal CLI chat turn, run one conversation, and return
  437. ``(final_response, run_result)``. Imports are local to keep CLI startup cheap. *ledger* (set when
  438. ``--usage-file`` is requested) attaches this run's auxiliary usage to the result."""
  439. from hermes_cli.config import load_config
  440. from hermes_cli.runtime_provider import resolve_runtime_with_fallback
  441. from hermes_cli.tools_config import _get_platform_tools
  442. from run_agent import AIAgent
  443. cfg = load_config()
  444. choice = _resolve_model_and_provider(cfg, model, provider)
  445. # Resume resolves BEFORE the runtime provider: the session's stored model/route must
  446. # replace the ambient config (see _apply_stored_session_runtime) and the ended row must
  447. # be reopened before the agent can stamp a new lifecycle boundary.
  448. session_db = _create_session_db_for_oneshot()
  449. resume_sid, conversation_history, resume_meta = _load_resume_target(session_db, resume)
  450. choice = _apply_stored_session_runtime(choice, resume_meta, explicit_model=bool((model or "").strip()))
  451. # Resolution-time fallback (#81209): a quota-exhausted/expired primary raises AuthError here, before
  452. # AIAgent (and its mid-session ``fallback_model`` wiring) exists, so walk the chain like the gateway.
  453. runtime, fallback_entry = resolve_runtime_with_fallback(
  454. cfg,
  455. requested=choice.provider,
  456. target_model=choice.model or None,
  457. explicit_base_url=choice.base_url,
  458. explicit_api_key=choice.api_key,
  459. )
  460. if fallback_entry is not None:
  461. # The chosen entry names the model that will be sent; the primary's stored api_mode no longer applies.
  462. choice = dataclasses.replace(choice, model=fallback_entry["model"], provider=runtime.get("provider"),
  463. api_mode=None)
  464. if choice.api_mode:
  465. runtime["api_mode"] = choice.api_mode
  466. from hermes_constants import parse_reasoning_effort, resolve_reasoning_config
  467. reasoning_config = resolve_reasoning_config(cfg, choice.model)
  468. if reasoning is not None and str(reasoning).strip():
  469. parsed_reasoning = parse_reasoning_effort(reasoning)
  470. if parsed_reasoning is None:
  471. logging.warning("Unknown --reasoning '%s', keeping the configured level", reasoning)
  472. else:
  473. reasoning_config = parsed_reasoning
  474. # sorted() gives stable ordering for config-derived sets; explicit values preserve user order.
  475. toolsets_list = _normalize_toolsets(toolsets)
  476. if toolsets_list is None and use_config_toolsets:
  477. toolsets_list = sorted(_get_platform_tools(cfg, "cli"))
  478. # Oneshot builds AIAgent directly, bypassing cli.py's MCP background discovery and
  479. # _init_agent's wait, so the construction-time tool snapshot would miss late MCP servers.
  480. # Idempotent start + bounded wait with the single-query bound (there is no later turn).
  481. # Ensure MCP tools are discovered before building the agent. This helper starts discovery if needed
  482. # (idempotent) and bounded-waits with the larger single-query bound (default 15s) because there is only
  483. # ONE turn and no between-turns late-binding refresh (#38448).
  484. from hermes_cli.mcp_startup import ensure_mcp_discovery_before_agent_build
  485. ensure_mcp_discovery_before_agent_build(logger=logging.getLogger(__name__), single_query=True)
  486. skills_prompt = _build_preloaded_skills_prompt(skills)
  487. # The try spans agent construction (not just ``chat``) so the store is always closed, even when
  488. # ``AIAgent(...)`` raises — the one-shot exit path hard-exits via os._exit and skips finalizers.
  489. agent = relay_session_id = None
  490. try:
  491. agent = AIAgent(
  492. api_key=runtime.get("api_key"),
  493. base_url=runtime.get("base_url"),
  494. provider=runtime.get("provider"),
  495. requested_provider=runtime.get("requested_provider"),
  496. api_mode=runtime.get("api_mode"),
  497. model=choice.model,
  498. enabled_toolsets=toolsets_list,
  499. quiet_mode=True,
  500. platform="cli",
  501. session_db=session_db,
  502. session_id=resume_sid,
  503. credential_pool=runtime.get("credential_pool"),
  504. fallback_model=get_fallback_chain(cfg) or None,
  505. # The resolved provider's request body (a custom entry's extra_body), as `hermes chat` passes it.
  506. request_overrides=runtime.get("request_overrides"),
  507. ephemeral_system_prompt=skills_prompt,
  508. reasoning_config=reasoning_config,
  509. # The only interactive callback wired: no user sits at a terminal. Sudo prompts gate on
  510. # HERMES_INTERACTIVE (never set), hook approval via HERMES_ACCEPT_HOOKS=1, dangerous
  511. # commands via HERMES_YOLO_MODE=1, skill secret capture degrades gracefully.
  512. clarify_callback=_oneshot_clarify_callback,
  513. )
  514. # Belt-and-braces: no streaming display callbacks may bypass our stdout capture.
  515. agent.suppress_status_output = True
  516. agent.stream_delta_callback = None
  517. agent.tool_gen_callback = None
  518. aux_before = _auxiliary_usage(session_db, resume_sid) if ledger else {}
  519. # Relay keys the root conversation to the id at turn entry; compression may rotate
  520. # agent.session_id mid-turn without opening a second root, so keep the entry id.
  521. relay_session_id = getattr(agent, "session_id", None)
  522. result = agent.run_conversation(prompt, conversation_history=conversation_history or None)
  523. if ledger:
  524. _attach_auxiliary_usage(result, session_db, aux_before,
  525. fallback_session_id=agent.session_id or resume_sid)
  526. return (result.get("final_response") or "", result)
  527. finally:
  528. _close_agent(agent, session_db, relay_session_id)
  529. def _quietly(what: str, fn) -> None:
  530. """Run a cleanup step, logging (never raising) on failure."""
  531. try:
  532. fn()
  533. except Exception:
  534. logging.debug("oneshot %s failed", what, exc_info=True)
  535. def _linger_for_background_completions() -> None:
  536. # Linger (bounded) for background processes this turn spawned with notify_on_complete=true BEFORE
  537. # agent.close(): close() calls process_registry.kill_all(task_id) and the dying parent owns the
  538. # children's stdout pipes, so exiting now destroys in-flight deliveries — including Bot Mode handoff
  539. # replies dispatched from a short-lived recipient (#90879).
  540. from tools.process_registry import process_registry
  541. process_registry.wait_for_pending_completions(None)
  542. def _close_agent(agent, session_db, relay_session_id=None) -> None:
  543. """Teardown mirroring gateway/run.py:_cleanup_agent_resources (NOT cli.py:_run_cleanup):
  544. oneshot has no _active_agent_ref and the hard-exit path skips finalizers."""
  545. if agent is not None:
  546. # Linger (bounded) for notify_on_complete background processes BEFORE agent.close():
  547. # close() kill_all()s the task and the dying parent owns the children's stdout pipes, so
  548. # exiting now destroys in-flight deliveries (e.g. Bot Mode handoff replies).
  549. _quietly("background completion wait", _linger_for_background_completions)
  550. if relay_session_id:
  551. # run_conversation ends the turn but keeps the Relay root resumable; one-shot has no
  552. # next turn and os._exit skips atexit, so close the root (and fire on_session_finalize).
  553. from hermes_cli.lifecycle import finalize_session
  554. _quietly("session finalize", lambda: finalize_session(
  555. session_id=relay_session_id, platform=getattr(agent, "platform", None) or "cli",
  556. reason="shutdown"))
  557. session_messages = getattr(agent, "_session_messages", None)
  558. memory_args = (session_messages,) if isinstance(session_messages, list) else ()
  559. _quietly("memory/context cleanup", lambda: agent.shutdown_memory_provider(*memory_args))
  560. _quietly("agent cleanup", lambda: agent.close())
  561. # agent.close() ends the session but leaves the connection open; close it to checkpoint the WAL.
  562. if session_db is not None:
  563. _quietly("session store cleanup", lambda: session_db.close())
  564. def _oneshot_clarify_callback(questions: list) -> dict:
  565. """Clarify is disabled in oneshot mode — tell the agent to pick a default and proceed."""
  566. return {"answers": {}, "outcome": "undelivered", "notice": (
  567. "oneshot mode: no user available. Pick the best choices using your own judgment, "
  568. "or make the most reasonable assumption you can, and continue.")}