kanban_decompose.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343
  1. """Kanban decomposer — fan a triage task out into a graph of child tasks.
  2. Invoked by ``hermes kanban decompose [task_id | --all]`` and the gateway
  3. dispatcher's auto-decompose path. Reads the profile roster (with
  4. descriptions), asks the auxiliary LLM for a task graph in JSON, then
  5. atomically creates the children, links them under the root, and flips the
  6. root ``triage -> todo``. The root stays alive as parent of every leaf child so
  7. it wakes back up when the graph completes and its assignee (the orchestrator
  8. profile) can judge completion and add more work.
  9. Mirrors ``kanban_specify`` (lazy aux import, lenient parse, never raises on
  10. expected failures). ``fanout=false`` collapses to the ``specify`` behaviour
  11. (tighten + promote, no children), making ``decompose`` a strict superset.
  12. Unknown assignees are rewritten to ``default_assignee`` — a child NEVER ends
  13. up with ``assignee=None``.
  14. """
  15. from __future__ import annotations
  16. import logging
  17. import re
  18. from dataclasses import dataclass
  19. from typing import Optional
  20. from hermes_cli import kanban_db as kb
  21. from hermes_cli.kanban_db_graph import decompose_triage_task
  22. from hermes_cli import kanban_db_connect as kbc
  23. from hermes_cli import profiles as profiles_mod
  24. from hermes_cli.kanban_specify import (
  25. _call_aux, _extract_json_blob, _load_triage_task, _task_prompt_fields, _title_body,
  26. )
  27. from hermes_cli.kanban_specify import _profile_author as _specify_author
  28. logger = logging.getLogger(__name__)
  29. _SYSTEM_PROMPT = """You are the Kanban decomposer for the Hermes Agent board.
  30. A user dropped a rough idea into the Triage column. Your job is to break it
  31. into a small graph of concrete child tasks and route each one to the best-
  32. matching profile from the available roster.
  33. You will be given:
  34. - The original task title and body
  35. - The list of available profiles (each with name + description)
  36. - The fallback "default_assignee" used when no profile fits
  37. Output a single JSON object with this exact shape:
  38. {
  39. "fanout": true,
  40. "rationale": "<one sentence on why this decomposition>",
  41. "tasks": [
  42. {
  43. "title": "<concrete task title, imperative voice, <= 80 chars>",
  44. "body": "<detailed spec for the worker on this child task>",
  45. "assignee": "<profile name from the roster, or null for default>",
  46. "parents": [<int>, ...]
  47. },
  48. ...
  49. ]
  50. }
  51. Rules:
  52. - "parents" is a list of INDICES (0-based) into this same "tasks" list,
  53. expressing actual data dependencies. Tasks with no parents run in
  54. PARALLEL. Tasks with parents wait until every parent completes.
  55. - Prefer parallelism. If two tasks can be done independently, give
  56. them no parents so the dispatcher fans them out at once.
  57. - Use 2-6 tasks for normal work. Don't create 20 tiny tasks. Don't
  58. cram everything into 1 task.
  59. - Pick assignees from the roster by matching the task to the profile's
  60. DESCRIPTION (not just the name). When nothing matches well, use null
  61. and the system will route to the default_assignee.
  62. - Each child task body is what a fresh worker will read with no other
  63. context — be specific about goal, approach, and acceptance criteria.
  64. When the task is genuinely a single unit of work (no useful decomposition),
  65. return:
  66. {
  67. "fanout": false,
  68. "rationale": "<one sentence>",
  69. "title": "<tightened title>",
  70. "body": "<concrete spec for a single worker>",
  71. "assignee": "<profile name from the roster, or null for default>"
  72. }
  73. In that case the task stays as one work item, just with a tightened spec and
  74. a concrete assignee. If no profile fits, use null and the system will route to
  75. the default_assignee.
  76. No preamble, no closing remarks, no code fences. Output only the JSON object.
  77. """
  78. _USER_TEMPLATE = """Task id: {task_id}
  79. Title: {title}
  80. Body:
  81. {body}
  82. Available profiles (assignees you may pick from):
  83. {roster}
  84. Default assignee (used when no profile fits a task): {default_assignee}
  85. """
  86. _FENCE_RE = re.compile(r"^```(?:json)?\s*|\s*```$", re.MULTILINE)
  87. @dataclass
  88. class DecomposeOutcome:
  89. """Result of decomposing a single triage task."""
  90. task_id: str
  91. ok: bool
  92. reason: str = ""
  93. fanout: bool = False
  94. child_ids: list[str] | None = None
  95. new_title: Optional[str] = None
  96. def _profile_author() -> str:
  97. """Mirror of ``hermes_cli.kanban._profile_author``."""
  98. return _specify_author("decomposer")
  99. def _resolve_profile_from_cfg(cfg: dict, key: str, *, fallback: Optional[str] = None) -> str:
  100. """``kanban.<key>`` if it names an existing profile, else ``fallback``
  101. (the root task's own assignee) if that does, else the active default
  102. profile — so a task is never stranded for lack of an owner.
  103. ``orchestrator_profile`` owns the root after fan-out; ``default_assignee``
  104. catches children the decomposer can't route.
  105. The root's assignee sits before the active profile because the decomposer
  106. runs inside whatever profile hosts the dispatcher — an operator's
  107. credential-less incognito profile, say — and that profile must never
  108. silently become the owner of work the card was assigned away from (#114294).
  109. """
  110. kanban_cfg = cfg.get("kanban", {}) if isinstance(cfg, dict) else {}
  111. explicit = (kanban_cfg.get(key) or "").strip()
  112. for candidate in (explicit, (fallback or "").strip()):
  113. if candidate:
  114. try:
  115. if profiles_mod.profile_exists(candidate):
  116. return candidate
  117. except Exception:
  118. pass
  119. try:
  120. return profiles_mod.get_active_profile_name() or "default"
  121. except Exception:
  122. return "default"
  123. def _build_roster() -> tuple[list[dict], set[str]]:
  124. """``(roster_for_prompt, valid_assignee_names)``; entries are
  125. ``{name, description, has_description}``."""
  126. try:
  127. all_profiles = profiles_mod.list_profiles()
  128. except Exception as exc:
  129. logger.warning("decompose: failed to list profiles: %s", exc)
  130. return [], set()
  131. roster = []
  132. for p in all_profiles:
  133. desc = (p.description or "").strip()
  134. roster.append({
  135. "name": p.name,
  136. "description": desc or f"(no description; profile named {p.name!r})",
  137. "has_description": bool(desc),
  138. })
  139. return roster, {p.name for p in all_profiles}
  140. def _format_roster(roster: list[dict]) -> str:
  141. if not roster:
  142. return " (no profiles installed — decomposer cannot route work)"
  143. return "\n".join(
  144. f" - {entry['name']}{'' if entry['has_description'] else ' ⚠ undescribed'}: {entry['description']}"
  145. for entry in roster
  146. )
  147. def _normalize_assignee_choice(assignee: object, *, default_assignee: str, valid_names: set[str]) -> str:
  148. """A valid assignee, else ``default_assignee`` — promoted work is never
  149. left unassigned."""
  150. if not isinstance(assignee, str) or not assignee.strip():
  151. return default_assignee
  152. chosen = assignee.strip()
  153. return chosen if chosen in valid_names else default_assignee
  154. @dataclass
  155. class _Routing:
  156. """Config-derived routing context for one decomposition."""
  157. orchestrator: str
  158. default_assignee: str
  159. auto_promote: bool
  160. roster: list[dict]
  161. valid_names: set[str]
  162. def _load_routing(*, root_assignee: Optional[str] = None) -> _Routing:
  163. from hermes_cli.config import load_config_readonly
  164. try:
  165. cfg = load_config_readonly()
  166. except Exception: # decompose_task promises ok=False, never a raise, on config trouble
  167. cfg = {}
  168. kanban_cfg = cfg.get("kanban", {}) if isinstance(cfg, dict) else {}
  169. roster, valid_names = _build_roster()
  170. return _Routing(
  171. orchestrator=_resolve_profile_from_cfg(cfg, "orchestrator_profile", fallback=root_assignee),
  172. default_assignee=_resolve_profile_from_cfg(cfg, "default_assignee", fallback=root_assignee),
  173. auto_promote=bool(kanban_cfg.get("auto_promote_children", True)),
  174. roster=roster,
  175. valid_names=valid_names,
  176. )
  177. def _apply_single(task: kb.Task, parsed: dict, routing: _Routing, author: str) -> DecomposeOutcome:
  178. """``fanout=false``: single-task spec promotion (same effect as specify)."""
  179. title_val, body_val = _title_body(parsed)
  180. assignee_val = None
  181. if not task.assignee:
  182. assignee_val = _normalize_assignee_choice(
  183. parsed.get("assignee"), default_assignee=routing.default_assignee, valid_names=routing.valid_names,
  184. )
  185. if title_val is None and body_val is None:
  186. return DecomposeOutcome(task.id, False, "decomposer returned fanout=false with no title/body")
  187. with kbc.connect_closing() as conn:
  188. ok = kb.specify_triage_task(
  189. conn, task.id, title=title_val, body=body_val, assignee=assignee_val, author=author,
  190. )
  191. if not ok:
  192. return DecomposeOutcome(task.id, False, "task moved out of triage before promotion")
  193. return DecomposeOutcome(task.id, True, "single task (no fanout)", fanout=False, new_title=title_val)
  194. def _clean_children(task_id: str, raw_tasks: list, routing: _Routing) -> tuple[list[dict], str]:
  195. """Validate/normalise the LLM's ``tasks`` list; ``(children, "")`` or ``([], reason)``.
  196. Unknown assignees route to the default; never assignee=None."""
  197. children: list[dict] = []
  198. for idx, entry in enumerate(raw_tasks):
  199. if not isinstance(entry, dict):
  200. return [], f"tasks[{idx}] is not an object"
  201. title = entry.get("title")
  202. if not isinstance(title, str) or not title.strip():
  203. return [], f"tasks[{idx}].title is missing or empty"
  204. body = entry.get("body")
  205. assignee = entry.get("assignee")
  206. chosen = _normalize_assignee_choice(
  207. assignee, default_assignee=routing.default_assignee, valid_names=routing.valid_names,
  208. )
  209. if isinstance(assignee, str) and assignee.strip() and assignee.strip() not in routing.valid_names:
  210. logger.info(
  211. "decompose: task %s child %d picked unknown assignee %r — "
  212. "routing to default_assignee %r",
  213. task_id, idx, assignee, routing.default_assignee,
  214. )
  215. parents = entry.get("parents") or []
  216. if not isinstance(parents, list):
  217. parents = []
  218. children.append({
  219. "title": title.strip()[:200],
  220. "body": body.strip() if isinstance(body, str) else "",
  221. "assignee": chosen,
  222. # Drop non-int, out-of-range and self parent indices.
  223. "parents": [p for p in parents if isinstance(p, int) and 0 <= p < len(raw_tasks) and p != idx],
  224. })
  225. return children, ""
  226. def _apply_fanout(task_id: str, parsed: dict, routing: _Routing, author: str) -> DecomposeOutcome:
  227. raw_tasks = parsed.get("tasks") or []
  228. if not isinstance(raw_tasks, list) or not raw_tasks:
  229. return DecomposeOutcome(task_id, False, "decomposer returned fanout=true with empty tasks list")
  230. children, reason = _clean_children(task_id, raw_tasks, routing)
  231. if reason:
  232. return DecomposeOutcome(task_id, False, reason)
  233. try:
  234. with kbc.connect_closing() as conn:
  235. child_ids = decompose_triage_task(
  236. conn,
  237. task_id,
  238. root_assignee=routing.orchestrator,
  239. children=children,
  240. author=author,
  241. auto_promote=routing.auto_promote,
  242. )
  243. except ValueError as exc:
  244. return DecomposeOutcome(task_id, False, f"DB rejected graph: {exc}")
  245. except Exception as exc:
  246. logger.exception("decompose: DB error on task %s", task_id)
  247. return DecomposeOutcome(task_id, False, f"DB error: {type(exc).__name__}")
  248. if child_ids is None:
  249. return DecomposeOutcome(task_id, False, "task already decomposed or moved out of triage")
  250. return DecomposeOutcome(
  251. task_id, True, f"decomposed into {len(child_ids)} children", fanout=True, child_ids=child_ids,
  252. )
  253. def decompose_task(
  254. task_id: str,
  255. *,
  256. author: Optional[str] = None,
  257. timeout: Optional[int] = None,
  258. ) -> DecomposeOutcome:
  259. """Decompose a triage task into a graph of child tasks. Expected failures
  260. (not in triage, no aux client, API error, malformed/empty reply) surface
  261. as ``ok=False``."""
  262. task, reason = _load_triage_task(task_id)
  263. if task is None:
  264. return DecomposeOutcome(task_id, False, reason)
  265. routing = _load_routing(root_assignee=task.assignee)
  266. raw, reason = _call_aux(
  267. "decompose", task_id, aux_task="kanban_decomposer", system=_SYSTEM_PROMPT,
  268. user=_USER_TEMPLATE.format(
  269. **_task_prompt_fields(task),
  270. roster=_format_roster(routing.roster),
  271. default_assignee=routing.default_assignee,
  272. ),
  273. max_tokens=4000, timeout=timeout or 180, log=logger,
  274. )
  275. if raw is None:
  276. return DecomposeOutcome(task_id, False, reason)
  277. parsed = _extract_json_blob(raw, _FENCE_RE)
  278. if parsed is None:
  279. return DecomposeOutcome(task_id, False, "LLM returned malformed JSON")
  280. audit_author = author or _profile_author()
  281. if not parsed.get("fanout"):
  282. return _apply_single(task, parsed, routing, audit_author)
  283. return _apply_fanout(task_id, parsed, routing, audit_author)
  284. def list_triage_ids(*, tenant: Optional[str] = None) -> list[str]:
  285. """Return task ids currently in the triage column."""
  286. with kbc.connect_closing() as conn:
  287. rows = kb.list_tasks(conn, status="triage", tenant=tenant, limit=1000)
  288. return [row.id for row in rows]