| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343 |
- """Kanban decomposer — fan a triage task out into a graph of child tasks.
- Invoked by ``hermes kanban decompose [task_id | --all]`` and the gateway
- dispatcher's auto-decompose path. Reads the profile roster (with
- descriptions), asks the auxiliary LLM for a task graph in JSON, then
- atomically creates the children, links them under the root, and flips the
- root ``triage -> todo``. The root stays alive as parent of every leaf child so
- it wakes back up when the graph completes and its assignee (the orchestrator
- profile) can judge completion and add more work.
- Mirrors ``kanban_specify`` (lazy aux import, lenient parse, never raises on
- expected failures). ``fanout=false`` collapses to the ``specify`` behaviour
- (tighten + promote, no children), making ``decompose`` a strict superset.
- Unknown assignees are rewritten to ``default_assignee`` — a child NEVER ends
- up with ``assignee=None``.
- """
- from __future__ import annotations
- import logging
- import re
- from dataclasses import dataclass
- from typing import Optional
- from hermes_cli import kanban_db as kb
- from hermes_cli.kanban_db_graph import decompose_triage_task
- from hermes_cli import kanban_db_connect as kbc
- from hermes_cli import profiles as profiles_mod
- from hermes_cli.kanban_specify import (
- _call_aux, _extract_json_blob, _load_triage_task, _task_prompt_fields, _title_body,
- )
- from hermes_cli.kanban_specify import _profile_author as _specify_author
- logger = logging.getLogger(__name__)
- _SYSTEM_PROMPT = """You are the Kanban decomposer for the Hermes Agent board.
- A user dropped a rough idea into the Triage column. Your job is to break it
- into a small graph of concrete child tasks and route each one to the best-
- matching profile from the available roster.
- You will be given:
- - The original task title and body
- - The list of available profiles (each with name + description)
- - The fallback "default_assignee" used when no profile fits
- Output a single JSON object with this exact shape:
- {
- "fanout": true,
- "rationale": "<one sentence on why this decomposition>",
- "tasks": [
- {
- "title": "<concrete task title, imperative voice, <= 80 chars>",
- "body": "<detailed spec for the worker on this child task>",
- "assignee": "<profile name from the roster, or null for default>",
- "parents": [<int>, ...]
- },
- ...
- ]
- }
- Rules:
- - "parents" is a list of INDICES (0-based) into this same "tasks" list,
- expressing actual data dependencies. Tasks with no parents run in
- PARALLEL. Tasks with parents wait until every parent completes.
- - Prefer parallelism. If two tasks can be done independently, give
- them no parents so the dispatcher fans them out at once.
- - Use 2-6 tasks for normal work. Don't create 20 tiny tasks. Don't
- cram everything into 1 task.
- - Pick assignees from the roster by matching the task to the profile's
- DESCRIPTION (not just the name). When nothing matches well, use null
- and the system will route to the default_assignee.
- - Each child task body is what a fresh worker will read with no other
- context — be specific about goal, approach, and acceptance criteria.
- When the task is genuinely a single unit of work (no useful decomposition),
- return:
- {
- "fanout": false,
- "rationale": "<one sentence>",
- "title": "<tightened title>",
- "body": "<concrete spec for a single worker>",
- "assignee": "<profile name from the roster, or null for default>"
- }
- In that case the task stays as one work item, just with a tightened spec and
- a concrete assignee. If no profile fits, use null and the system will route to
- the default_assignee.
- No preamble, no closing remarks, no code fences. Output only the JSON object.
- """
- _USER_TEMPLATE = """Task id: {task_id}
- Title: {title}
- Body:
- {body}
- Available profiles (assignees you may pick from):
- {roster}
- Default assignee (used when no profile fits a task): {default_assignee}
- """
- _FENCE_RE = re.compile(r"^```(?:json)?\s*|\s*```$", re.MULTILINE)
- @dataclass
- class DecomposeOutcome:
- """Result of decomposing a single triage task."""
- task_id: str
- ok: bool
- reason: str = ""
- fanout: bool = False
- child_ids: list[str] | None = None
- new_title: Optional[str] = None
- def _profile_author() -> str:
- """Mirror of ``hermes_cli.kanban._profile_author``."""
- return _specify_author("decomposer")
- def _resolve_profile_from_cfg(cfg: dict, key: str, *, fallback: Optional[str] = None) -> str:
- """``kanban.<key>`` if it names an existing profile, else ``fallback``
- (the root task's own assignee) if that does, else the active default
- profile — so a task is never stranded for lack of an owner.
- ``orchestrator_profile`` owns the root after fan-out; ``default_assignee``
- catches children the decomposer can't route.
- The root's assignee sits before the active profile because the decomposer
- runs inside whatever profile hosts the dispatcher — an operator's
- credential-less incognito profile, say — and that profile must never
- silently become the owner of work the card was assigned away from (#114294).
- """
- kanban_cfg = cfg.get("kanban", {}) if isinstance(cfg, dict) else {}
- explicit = (kanban_cfg.get(key) or "").strip()
- for candidate in (explicit, (fallback or "").strip()):
- if candidate:
- try:
- if profiles_mod.profile_exists(candidate):
- return candidate
- except Exception:
- pass
- try:
- return profiles_mod.get_active_profile_name() or "default"
- except Exception:
- return "default"
- def _build_roster() -> tuple[list[dict], set[str]]:
- """``(roster_for_prompt, valid_assignee_names)``; entries are
- ``{name, description, has_description}``."""
- try:
- all_profiles = profiles_mod.list_profiles()
- except Exception as exc:
- logger.warning("decompose: failed to list profiles: %s", exc)
- return [], set()
- roster = []
- for p in all_profiles:
- desc = (p.description or "").strip()
- roster.append({
- "name": p.name,
- "description": desc or f"(no description; profile named {p.name!r})",
- "has_description": bool(desc),
- })
- return roster, {p.name for p in all_profiles}
- def _format_roster(roster: list[dict]) -> str:
- if not roster:
- return " (no profiles installed — decomposer cannot route work)"
- return "\n".join(
- f" - {entry['name']}{'' if entry['has_description'] else ' ⚠ undescribed'}: {entry['description']}"
- for entry in roster
- )
- def _normalize_assignee_choice(assignee: object, *, default_assignee: str, valid_names: set[str]) -> str:
- """A valid assignee, else ``default_assignee`` — promoted work is never
- left unassigned."""
- if not isinstance(assignee, str) or not assignee.strip():
- return default_assignee
- chosen = assignee.strip()
- return chosen if chosen in valid_names else default_assignee
- @dataclass
- class _Routing:
- """Config-derived routing context for one decomposition."""
- orchestrator: str
- default_assignee: str
- auto_promote: bool
- roster: list[dict]
- valid_names: set[str]
- def _load_routing(*, root_assignee: Optional[str] = None) -> _Routing:
- from hermes_cli.config import load_config_readonly
- try:
- cfg = load_config_readonly()
- except Exception: # decompose_task promises ok=False, never a raise, on config trouble
- cfg = {}
- kanban_cfg = cfg.get("kanban", {}) if isinstance(cfg, dict) else {}
- roster, valid_names = _build_roster()
- return _Routing(
- orchestrator=_resolve_profile_from_cfg(cfg, "orchestrator_profile", fallback=root_assignee),
- default_assignee=_resolve_profile_from_cfg(cfg, "default_assignee", fallback=root_assignee),
- auto_promote=bool(kanban_cfg.get("auto_promote_children", True)),
- roster=roster,
- valid_names=valid_names,
- )
- def _apply_single(task: kb.Task, parsed: dict, routing: _Routing, author: str) -> DecomposeOutcome:
- """``fanout=false``: single-task spec promotion (same effect as specify)."""
- title_val, body_val = _title_body(parsed)
- assignee_val = None
- if not task.assignee:
- assignee_val = _normalize_assignee_choice(
- parsed.get("assignee"), default_assignee=routing.default_assignee, valid_names=routing.valid_names,
- )
- if title_val is None and body_val is None:
- return DecomposeOutcome(task.id, False, "decomposer returned fanout=false with no title/body")
- with kbc.connect_closing() as conn:
- ok = kb.specify_triage_task(
- conn, task.id, title=title_val, body=body_val, assignee=assignee_val, author=author,
- )
- if not ok:
- return DecomposeOutcome(task.id, False, "task moved out of triage before promotion")
- return DecomposeOutcome(task.id, True, "single task (no fanout)", fanout=False, new_title=title_val)
- def _clean_children(task_id: str, raw_tasks: list, routing: _Routing) -> tuple[list[dict], str]:
- """Validate/normalise the LLM's ``tasks`` list; ``(children, "")`` or ``([], reason)``.
- Unknown assignees route to the default; never assignee=None."""
- children: list[dict] = []
- for idx, entry in enumerate(raw_tasks):
- if not isinstance(entry, dict):
- return [], f"tasks[{idx}] is not an object"
- title = entry.get("title")
- if not isinstance(title, str) or not title.strip():
- return [], f"tasks[{idx}].title is missing or empty"
- body = entry.get("body")
- assignee = entry.get("assignee")
- chosen = _normalize_assignee_choice(
- assignee, default_assignee=routing.default_assignee, valid_names=routing.valid_names,
- )
- if isinstance(assignee, str) and assignee.strip() and assignee.strip() not in routing.valid_names:
- logger.info(
- "decompose: task %s child %d picked unknown assignee %r — "
- "routing to default_assignee %r",
- task_id, idx, assignee, routing.default_assignee,
- )
- parents = entry.get("parents") or []
- if not isinstance(parents, list):
- parents = []
- children.append({
- "title": title.strip()[:200],
- "body": body.strip() if isinstance(body, str) else "",
- "assignee": chosen,
- # Drop non-int, out-of-range and self parent indices.
- "parents": [p for p in parents if isinstance(p, int) and 0 <= p < len(raw_tasks) and p != idx],
- })
- return children, ""
- def _apply_fanout(task_id: str, parsed: dict, routing: _Routing, author: str) -> DecomposeOutcome:
- raw_tasks = parsed.get("tasks") or []
- if not isinstance(raw_tasks, list) or not raw_tasks:
- return DecomposeOutcome(task_id, False, "decomposer returned fanout=true with empty tasks list")
- children, reason = _clean_children(task_id, raw_tasks, routing)
- if reason:
- return DecomposeOutcome(task_id, False, reason)
- try:
- with kbc.connect_closing() as conn:
- child_ids = decompose_triage_task(
- conn,
- task_id,
- root_assignee=routing.orchestrator,
- children=children,
- author=author,
- auto_promote=routing.auto_promote,
- )
- except ValueError as exc:
- return DecomposeOutcome(task_id, False, f"DB rejected graph: {exc}")
- except Exception as exc:
- logger.exception("decompose: DB error on task %s", task_id)
- return DecomposeOutcome(task_id, False, f"DB error: {type(exc).__name__}")
- if child_ids is None:
- return DecomposeOutcome(task_id, False, "task already decomposed or moved out of triage")
- return DecomposeOutcome(
- task_id, True, f"decomposed into {len(child_ids)} children", fanout=True, child_ids=child_ids,
- )
- def decompose_task(
- task_id: str,
- *,
- author: Optional[str] = None,
- timeout: Optional[int] = None,
- ) -> DecomposeOutcome:
- """Decompose a triage task into a graph of child tasks. Expected failures
- (not in triage, no aux client, API error, malformed/empty reply) surface
- as ``ok=False``."""
- task, reason = _load_triage_task(task_id)
- if task is None:
- return DecomposeOutcome(task_id, False, reason)
- routing = _load_routing(root_assignee=task.assignee)
- raw, reason = _call_aux(
- "decompose", task_id, aux_task="kanban_decomposer", system=_SYSTEM_PROMPT,
- user=_USER_TEMPLATE.format(
- **_task_prompt_fields(task),
- roster=_format_roster(routing.roster),
- default_assignee=routing.default_assignee,
- ),
- max_tokens=4000, timeout=timeout or 180, log=logger,
- )
- if raw is None:
- return DecomposeOutcome(task_id, False, reason)
- parsed = _extract_json_blob(raw, _FENCE_RE)
- if parsed is None:
- return DecomposeOutcome(task_id, False, "LLM returned malformed JSON")
- audit_author = author or _profile_author()
- if not parsed.get("fanout"):
- return _apply_single(task, parsed, routing, audit_author)
- return _apply_fanout(task_id, parsed, routing, audit_author)
- def list_triage_ids(*, tenant: Optional[str] = None) -> list[str]:
- """Return task ids currently in the triage column."""
- with kbc.connect_closing() as conn:
- rows = kb.list_tasks(conn, status="triage", tenant=tenant, limit=1000)
- return [row.id for row in rows]
|