(Gj RUdZddlmZddlZddlZddlZddlmZmZddl m Z ddl m Z ddl mZmZddlmZmZejeZd Zd Zdd ZddZddZddZddZddZddZdddZe ddhZ!dd Z"d!Z#d"a$d#e%d$<dd%Z&dd(Z'dd*Z(d+d,dd1Z)dd3Z*dd5Z+dd6Z,dd7Z-dd8Z.dd9Z/dd:Z0dd;Z1dd<Z2dd>Z3dd?Z4dd@Z5dAZ6dBZ7ddDZ8dEdFdGdHe6dIe8dJgdKdLZ9dMdNdGdHdOdIdHgdPdQdRdHdSdIdTdUdIdVdWdIe8dXgdKdLZ:dYdZdGdHe6dIdHd[dIdGd\dIdHd]dId^d_dHid`dad^d_dHidbdae8dcgdKdLZ;dddedGdHe6dIdHdfdIdHgdgdhdRe8didjgdKdLZdudvdGidwdHdxdIdydHdzdIdtdHd{dId|d^d_dHid}dad~dHddIddVddIddHgdddRddHddIddHddIddTddIddHddIddVddIddHddgddRdd^d_dHiddaddTddIddVddIde8dwdygdKdLZ?dddGdHddIe8dJdgdKdLZ@dddGdHddIdHddIe8dddgdKdLZAejBdEde9e,edejBdMde:e-edejBdYde;e.edejBdddee1edejBdude?e2edejBdde@e4edejBddeAe5eddS)uzKanban tools — structured tool-call surface for worker + orchestrator agents. These tools are registered into the model's schema when the agent is running under the dispatcher (env var ``HERMES_KANBAN_TASK`` set) or when the active profile explicitly enables the ``kanban`` toolset for orchestrator work. A normal ``hermes chat`` session still sees **zero** kanban tools in its schema unless configured. Why tools instead of just shelling out to ``hermes kanban``? 1. **Backend portability.** A worker whose terminal tool points at Docker / Modal / Singularity / SSH would run ``hermes kanban complete …`` inside the container, where ``hermes`` isn't installed and the DB isn't mounted. Tools run in the agent's Python process, so they always reach ``~/.hermes/kanban.db`` regardless of terminal backend. 2. **No shell-quoting footguns.** Passing ``--metadata '{"x": [...]}'`` through shlex+argparse is fragile. Structured tool args skip it. 3. **Better errors.** Tool-call failures return structured JSON the model can reason about, not stderr strings it has to parse. Humans continue to use the CLI (``hermes kanban …``), the dashboard (``hermes dashboard``), and the slash command (``/kanban …``) — all three bypass the agent entirely. The tools are for dispatcher-spawned worker handoffs and for configured orchestrator profiles that route work through the board. ) annotationsN)AnyOptional)redact_sensitive_text) judge_goal)registry tool_error)cfg_get load_config2returnboolcz ddlm}|}|dg}d|vS#t$rYdSwxYw)Nr)r toolsetskanbanF)hermes_cli.configr get Exception)r cfgrs 8/home/rurouni/.hermes/hermes-agent/tools/kanban_tools.py_profile_has_kanban_toolsetr4sd111111kmm77:r**8## uus ), ::c`tjdrdStS)aTask-lifecycle tools are available when: 1. ``HERMES_KANBAN_TASK`` is set (dispatcher-spawned worker), OR 2. The current profile has ``kanban`` in its toolsets config (orchestrator profiles like techlead that route work via Kanban). Humans running ``hermes chat`` without the kanban toolset see zero kanban tools. Workers spawned by the kanban dispatcher (gateway- embedded by default) and orchestrator profiles with the kanban toolset enabled see the Kanban lifecycle tool surface. HERMES_KANBAN_TASKTosenvironrrr_check_kanban_moder As, z~~*++t & ( ((rc`tjdrdStS)aBoard-routing tools (kanban_list, kanban_unblock) are intentionally hidden from task workers. Dispatcher-spawned workers should close their own task via the lifecycle tools (complete/block/heartbeat), not enumerate or unblock board state. Profiles that explicitly opt into the kanban toolset and are NOT scoped to a single task are the orchestrator surface. rFrrrr_check_kanban_orchestrator_moder"Rs, z~~*++u & ( ((rarg Optional[str]cP|r|Stjd}|pdS)zGResolve ``task_id`` arg or fall back to the env var the dispatcher set.rN)rrr)r#env_tids r_default_task_idr'ds-  jnn122G ?drtask_idstr Optional[int]ctjd|krdStjd}|sdS t|S#t$rYdSwxYw)zDReturn this worker's dispatcher run id when it is scoped to task_id.rNHERMES_KANBAN_RUN_ID)rrrint ValueError)r(raws r_worker_run_idr0lst z~~*++w66t *../ 0 0C t3xx tts A A'&A'metadataOptional[dict]ctjd|kr|Stjd}|s|St|pi}||d<|S)zBAdd trusted worker session id metadata for this worker's own task.rHERMES_SESSION_IDworker_session_id)rrrdict)r(r1 session_idstampeds r_stamp_worker_session_metadatar9yse z~~*++w66 344J 8>r""G#-G  Nrtidctjd}|sdS||krtd|d|dSdS)u_Reject worker-driven destructive calls on foreign task IDs. A process spawned by the dispatcher has ``HERMES_KANBAN_TASK`` set to its own task id. Tools like ``kanban_complete`` / ``kanban_block`` / ``kanban_heartbeat`` mutate run-lifecycle state, so a buggy or prompt-injected worker that passed an explicit ``task_id`` for some other task could corrupt sibling or cross-tenant runs (see #19534). Orchestrator profiles (kanban toolset enabled but **no** ``HERMES_KANBAN_TASK`` in env) aren't subject to this check — their job is routing, and they sometimes legitimately close out child tasks or reopen blocked ones. Workers are narrowly scoped to their one task. Returns ``None`` when the call is allowed, or a tool-error string when it must be rejected. Callers should ``return`` the error verbatim. rNzworker is scoped to task z; refusing to mutate zf. Use kanban_comment to hand off information to other tasks, or kanban_create to spawn follow-up work.rrrr )r:r&s r_enforce_worker_task_ownershipr=sp&jnn122G t g~~ @ @ @ @ @ @   4rboardc>ddlm}|||fS)uImport + connect lazily so the module imports cleanly in non-kanban contexts (e.g. test rigs that import every tool module). When ``board`` is provided it's forwarded to :func:`kb.connect`, which routes the connection to that board's sqlite file. ``None`` (the default) preserves the legacy resolution chain (``HERMES_KANBAN_DB`` → ``HERMES_KANBAN_BOARD`` env → current symlink → ``default``). Per-tool ``board`` lets a Telegram-side agent override the env-pinned active board without restarting Hermes. r kanban_dbr>) hermes_clirAconnect)r>kbs r_connectrFs/+***** rzzz&& &&r dependency needs_inputcv ddlm}|d\}}n#t$rYdSwxYw|duot|S)apTrue when an auxiliary client is configured for the goal judge. ``judge_goal`` is fail-open at the source: when no auxiliary model can be reached it returns a ``"continue"`` verdict that is indistinguishable from a real "not done yet" judgment. The completion gate must not treat that as a rejection, or an unconfigured/degraded auxiliary model would wedge every ``goal_mode`` worker (it could never close its own task). So we probe availability first and only enforce the gate when a judge is actually reachable. This mirrors the same client lookup ``judge_goal`` performs internally. r)get_text_auxiliary_client goal_judgeFN)agent.auxiliary_clientrJrr)rJclientmodels r_goal_judge_availablerOsgDDDDDD11,??  uu   -$u++-s  %%gN@gfloat_auto_heartbeat_last_attemptctjd}|sdSddl}|}|t z t krdS|a t\}} tjd} ||||n,#t$rt dd YnwxYwtjd } |rt|nd}n#ttf$rd}YnwxYw |||d| n,#t$rt d d YnwxYw |n:#t$rYn.wxYw# |w#t$rYwwxYwxYwdS#t$r t d d YdSwxYw)uBest-effort: extend the kanban claim + bump board heartbeat for the current dispatcher-spawned worker, using identity from env vars. Returns True if a write was attempted (whether or not it succeeded); False if the call was skipped (not a kanban worker, rate-limited, or swallowed exception). The boolean is informational — callers should not branch on it. Identity comes from: * ``HERMES_KANBAN_TASK`` — task id (required; absence means no-op) * ``HERMES_KANBAN_RUN_ID`` — pins the run row so we don't heartbeat a stale run that may have already been reclaimed * ``HERMES_KANBAN_CLAIM_LOCK`` — claim lock for ``heartbeat_claim``; falls back to the default ``_claimer_id()`` for locally-driven workers that never went through the dispatcher path Rate-limited via the module-level ``_auto_heartbeat_last_attempt`` timestamp (monotonic clock); not thread-safe in the strict sense, but the worst case is one extra DB write per race, which is harmless. rFrNHERMES_KANBAN_CLAIM_LOCKclaimerz&auto-heartbeat: heartbeat_claim failedTexc_infor,noteexpected_run_idz'auto-heartbeat: heartbeat_worker failedzauto-heartbeat: bridge failed)rrrtime monotonicrQ$_AUTO_HEARTBEAT_MIN_INTERVAL_SECONDSrFheartbeat_claimrloggerdebugr- TypeErrorr.heartbeat_workerclose)r:_timenowrEconn claim_lock run_id_rawrun_ids r!heartbeat_current_worker_from_envrjsN, *..- . .C u //  C **.RRRu#& ::D (BCCJ V""4j"AAAA V V V EPT UUUUU V(>??J ,6@ZDz*     W##D#D&#QQQQ W W W FQU VVVVV W            t  4t DDDuusF1&FBF&CFC"F+C?>F?DFDFD32F3&EFEF E54F15 F?F1FF1F,FF, F)&F,(F))F,,F11&GGfieldsrc 2tjddi|S)NokT)jsondumps)rks r_okrp"s :tT,V, - --rvaluec|dSt|}|r|dvrdS|S)zANormalize CLI-compatible assignee sentinels for the tool surface.N>-nonenull)r)striplower)rqtexts r_normalize_profilery&sH }t u::    D 4::<<#888t KrFdefaultargsr6namer{c||}||dfSt|tr|dfSt|}|dvrdS|dvrdS||dfS)N>1yestrue)TN>0nofalse)FNz$ must be a boolean or 'true'/'false')r isinstancerr)rvrw)r|r}r{rqrxs r_parse_bool_argr0s HHTNNE }}%d{ u::     # # % %D ###z ###{ tAAA AAr tool_namechtjdrt|dSdS)aBelt-and-suspenders runtime guard for orchestrator-only handlers. The check_fn (`_check_kanban_orchestrator_mode`) keeps these tools out of the worker schema entirely, but in case a stale registration or test harness routes a worker to one of them anyway, return a structured tool_error so the model gets a clear refusal instead of silently mutating board state from a worker context. rz is orchestrator-only; dispatcher-spawned workers must use kanban_complete, kanban_block, kanban_heartbeat, or kanban_comment for their assigned task.Nr<)rs r_require_orchestrator_toolr>sF z~~*++  6 6 6   4rdict[str, Any]c|||j}|||j}id|jd|jd|jd|jd|jd|jd|jd|j d |j d |j d |j d |j d |jd|jd|jd|d|t#|t#|dS)z+Compact task shape for board-listing tools.idtitleassigneestatusprioritytenantworkspace_kindworkspace_path project_id created_by created_at started_at completed_atcurrent_run_idmodel_overrideparentschildren) parent_count child_count) parent_idsr child_idsrrrrrrrrrrrrrrlen)rErftaskrrs r_task_summary_dictrPsDmmD$'**G||D$'**H  dg   DM  $+   DM   $+   $-  $-  do  do  do  do  )  $-  $-  7! " H# $G 8}}'   rc t|d}|stdS|d} t|\}} |||}|'td|d|S|||}|||}|||} | ||} | ||} d} d tj | || | d |Dd |d dDfd | D| ||d|S#|wxYw#t$r} td| cYd} ~ Sd} ~ wt$r6} t dtd| cYd} ~ Sd} ~ wwxYw)zsRead a task's full state: task row, parents, children, comments, runs (attempt history), and the last N events.r(:task_id is required (or set HERMES_KANBAN_TASK in the env)r>rBNztask z not foundcid|jd|jd|jd|jd|jd|jd|jd|jd |jd |j d |j d |j d |j d|j d|jd|jS)Nrrbodyrrrrrrrrrrresultrr)rrrrrrrrrrrrrrrr)ts r _task_dictz _handle_show.._task_dicts !$  ' 28!&   ,4ah ah )3AJ %a&6  %a&6  !!,  1=al !!, #AN ah %a&6 %a&6  rc t|j|j|j|j|j|j|j|j|jd S)N rprofileroutcomesummaryerrorr1rended_atr)rs r _run_dictz_handle_show.._run_dicts:$19h19 y17 ! "#,AJ rc8g|]}|j|j|jdS)authorrrr.0cs r z _handle_show..s? !x#$<11rcDg|]}|j|j|j|jdS)kindpayloadrrir)res rrz _handle_show..sEV #$<18EEric&g|] }|Srr)rrrs rrz _handle_show..s!444!1444r)rrrcommentseventsrunsworker_contextz kanban_show: zkanban_show failed)r'rr rFget_taskrc list_comments list_events list_runsrrrnrobuild_worker_contextr.rr_ exception)r|kwr:r>rErfrrrrrrrrrs @r _handle_showros 488I.. / /C   H    HHW  E@/%(((D8 ;;tS))D|!"9#"9"9"9::j JJLLLLi''c22H^^D#..F<<c**DmmD#..G||D#..H      :" 4(("$& $CDD\ 5444t444 #%"9"9$"D"D', JJLLLLDJJLLLL ///-!--........ ///-...-!--......../sU F *F F CF2F FF H*G;H H+G?9H?Hc td}|r|S|d}|d}|d}t|d\}}|rt|S|d}|t} t |}n&#t tf$rtdcYSwxYw|d krtd S|tkrtd tS|d } t| \  }  |||||d z} t| |k} | d|} tjfd| Dt| || | r#|tkrt|dztnd| dS#wxYw#t$r}td|cYd}~Sd}~wt"$r6}t$dtd|cYd}~Sd}~wwxYw)z:List task summaries with the same core filters as the CLI. kanban_listrrrinclude_archivedlimitNzlimit must be an integerzlimit must be >= 1zlimit must be <= r>rB)rrrrrc2g|]}t|Sr)r)rrrfrEs rrz _handle_list..s&IIIa,Rq99IIIr)taskscountr truncated next_limitpromotedz kanban_list: zkanban_list failed)rrrr KANBAN_LIST_DEFAULT_LIMITr-rar.KANBAN_LIST_MAX_LIMITrFrecompute_ready list_tasksrrnrominrcrr_r)r|rguardrrrr bool_errorrr>rrowsrrrrfrEs @@r _handle_listrs &} 5 5E  xx ##H XXh  F XXh  F#249K#L#L j&*%%% HHW  E })6E  z "6664555556 qyy./// $$$E.CEEFFF HHW  E#/%(((D ))$//H==!!1ai !DD E)I%LE:IIIII5IIIU&!M%*-B%B%B #8999HL$     JJLLLLDJJLLLL ///-!--........ ///-...-!--......../s[B(( C  C H/B)G-H-HH I*H'!I*' I*4+I%I*%I*c  t|d}|stdSt|}|r|S|d}|d}|d}|rt t |d}|rt t |d}|et |trPtj |}t |d} tj |}n#tj $rYnwxYw|d }|d } |dt |t r|g}t |ttfs$td t|jSd |D}| Vt | t r| g} t | ttfs$td t| jSd| D} | r|i}n9t |ts$tdt|jS|d } t | ttfr|g} t!} t| | zD]S} t | }|r.|| vr*| || |T| |d <n| |d <|s|stdS|9t |ts$tdt|jSt)||}|d} t+|\}} |||}|r|jrt1rd}d} t3|jd|jpd|p|pd\}}}n4#t8$r'}t:d|dYd}~nd}~wwxYw|dkr*td|d|d|S | ||||||tC|}nV#|j"$rI}tdd#|j$dcYd}~|Sd}~wwxYw|s'td |d!|S|%||}tM||r|j'nd"|S#|wxYw#tP$r}td#|cYd}~Sd}~wt8$r6}t:)d$td#|cYd}~Sd}~wwxYw)%z5Mark the current task done with a structured handoff.r(rrr1rTforceN created_cards artifactsz.created_cards must be a list of task ids, got cg|]D}t|#t|ESrr)rvrs rrz$_handle_complete..sI    SVV\\^^ FFLLNN   rz,artifacts must be a list of file paths, got cg|]D}t|#t|ESrr)rps rrz$_handle_complete..(sI    Q FFLLNN   rz%metadata must be an object/dict, got z4provide at least one of: summary (preferred), resultr>rBdonez )goal last_responsez0goal judge check failed, allowing completion: %srVz#Goal completion rejected by judge: z. To proceed, either: (1) provide explicit acceptance evidence in your summary matching the task's criteria, or (2) create continuation tasks with parents=[z] and keep this task alive.)rrr1rrZzfkanban_complete blocked: the following created_cards do not exist or were not created by this worker: z, z. Your task is still in-flight (no state change). Retry kanban_complete with the same summary/metadata and either drop these ids from created_cards, or pass created_cards=[] to skip the card-claim check entirely.zcould not complete z! (unknown id or already terminal))r(rizkanban_complete: zkanban_complete failed)*r'rr r=rr)rr6rnroloadsJSONDecodeErrorlisttupletype__name__setrvaddappendr9rFr goal_moderOrrrrr_warningrc complete_taskr0HallucinatedCardsErrorjoinphantom latest_runrprr.r)r|rr: ownership_errrr1r meta_jsonrrexistingmergedseenitemsr>rErfrverdictreason_ judge_excrmhall_errrunrs r_handle_completer s8 488I.. / /C   H   3377Mhhy!!Gxx ##H XXh  FB'G DAAA @&s6{{$??? 8T : :Jx(( ))4@@@  z),,HH#    D HH_--M%%I mS ) ) ,*OM-$77 2 &&/22    $1    i % % $" I)dE]33 . ??+..   $-     2$// !1H~~.11  ||K00H(T5M22 2$&!$ NNY6))DD ))A)Qd]]  a((((.%%(1%  v  B   Jx$>$> MDNN4K M M   .c8<&'>B&E&E&G&G***&GVQQ!NNJ!!%#f$$%5f55KN555T JJLLLLE %%#!7X"/$23$7$7 & ,   "Oyy!122OOO JJLLLL7 ( !P#PPP JJLLLL--c**CsS+B366dCCC JJLLLLDJJLLLL 3331a1122222222 33312221a11222222223sDD*)D* V 1U1APU1 Q)Q U1 QU1.V )R.-U1. T8*S<"T#U1'V <TU1V -/U1V 1VV W.V+%W.+ W.8+W)#W.)W.c t|d}|stdSt|}|r|S|d}|r!t |stdSt t |d}|d}|d} t| \}}|B||jvr9| td t|jd S| ||} | rL| j rE|tvr<| td ttd|dS |||||t|} | s'td|d| S|||} | ||} t#|| r| jnd | r| jnd|| S#| wxYw#t($r} td| cYd } ~ Sd } ~ wt*$r6} t,dtd| cYd } ~ Sd } ~ wwxYw)z?Transition the task to blocked with a reason a human will read.r(rru2reason is required — explain what input you needTrrr>rBNzkind must be one of z (or omit it)z,goal_mode tasks can only block with kind in z (got u). If the task is actually finished or cannot proceed for another reason, call kanban_complete instead — the completion judge will evaluate it.)rrrZzcould not block z% (unknown id or not in running/ready)blocked)r(rir block_kindzkanban_block: zkanban_block failed)r'rr r=r)rvrrFVALID_BLOCK_KINDSrcsortedrr_GOAL_MODE_BLOCK_ALLOWED_KINDS block_taskr0rrprrr.rr_r)r|rr:rrrr>rErfrrmr landedrs r _handle_blockrs? 488I.. / /C   H   3377M XXh  F PV**,,PNOOO "3v;;d ; ; ;F 88F  D HHW  E;0%(((D  B,@ @ @ JJLLLRvb.B'C'CRRR {{4%%   ::: JJLLL689966AE666  c .s 3 3 B  !&s&&& JJLLLL--c**C[[s++F!$.svv$(.=v}}I  JJLLLLDJJLLLL 000.1..//////// 000.///.1..////////0s]AI!.A#I!;II!#AI3I!II!! K+J<K K+K:KKc `t|d}|stdSt|}|r|S|d}|d} t |\}} t jd}||||||||t|} | s'td |d | St| | S#| wxYw#t$r} td | cYd } ~ Sd } ~ wt$r6} tdtd | cYd } ~ Sd } ~ wwxYw)uSignal that the worker is still alive during a long operation. Extends the claim TTL via ``heartbeat_claim`` AND records a heartbeat event via ``heartbeat_worker``. Without the ``heartbeat_claim`` half, a diligent worker that loops this tool while a single tool call blocks the agent for >DEFAULT_CLAIM_TTL_SECONDS still gets reclaimed by ``release_stale_claims`` — which is exactly the trap that ``heartbeat_claim``'s docstring warns against. r(rrYr>rBrSrTrXzcould not heartbeat z (unknown id or not running))r(zkanban_heartbeat: Nzkanban_heartbeat failed)r'rr r=rFrrr^rbr0rcrpr.rr_r) r|rr:rrYr>rErfrgrmrs r_handle_heartbeatrs 488I.. / /C   H   3377M 88F  D HHW  E4%(((D  (BCCJ   tS*  = = =$$ .s 3 3 %B  !L3LLL JJLLLLs### JJLLLLDJJLLLL 4442q2233333333 44423332q22333333334sU2E A1D07E D0E 0EE F-E*$F-* F-7+F("F-(F-c D|d}|stdS|d}|r!t|stdSt t|d}t jdpd}|d } t| \}} ||||t| }t|| | S#| wxYw#t$r} td | cYd} ~ Sd} ~ wt$r6} tdtd | cYd} ~ Sd} ~ wwxYw)z$Append a comment to a task's thread.r(uotask_id is required (use the current task id if that's what you mean — pulls from env but kept explicit here)rzbody is requiredTrHERMES_PROFILEworkerr>rB)rr)r( comment_idzkanban_comment: Nzkanban_comment failed)rr r)rvrrrrF add_commentrprcr.rr_r) r|rr:rrr>rErfcidrs r_handle_commentrs ((9  C   B    88F  D .s4yy((.,--- T$ 7 7 7DZ^^, - - 9F HHW  E 2%(((D ..s6D .JJCss333 JJLLLLDJJLLLL 2220Q0011111111 22201110Q00111111112sHD;6D" D;"D88D;; FEF F)+FFFc  |d}|r!t|stdS|d}|stdS|d}|dpg}|dptjd}|d ptjd }|d }|d } |d } |dp|d} | duo| du} | d} t |d\} }|rt|S|d}|d}|dpd}|d}t|tr|g}|@t|ttfs$tdt|j St |d\}}|rt|S|d}t|tr|g}t|ttfs$tdt|j S|d} t|\}} | r^tjd}|r=| ||}|%|jr|j} |j} | |jr|j} ||t||t|t|||t%|ndt| | | | ||t%|nd|||t%|ndt|tjd pd!|"}| ||}t'||}t)||r|jnd|#|S#|wxYw#t.$r}td$|cYd}~Sd}~wt0$r6}t2d%td$|cYd}~Sd}~wwxYw)&zCreate a child task. Orchestrator workers use this to fan out. ``parents`` can be a list of task ids; dependency-gated promotion works as usual. rztitle is requiredruassignee is required — name the profile that should execute this task (the dispatcher will only spawn tasks with an assignee)rrr HERMES_TENANTr7r4rrrprojectrNscratchtriageidempotency_keymax_runtime_secondsinitial_statusrunningskillsz*skills must be a list of skill names, got rgoal_max_turnsz(parents must be a list of task ids, got r>rBrrrr)rrrrrrrrrr#r$r%r(rr)r&rr7)r(r subscribedzkanban_create: zkanban_create failed)rr)rvr rrrrrrrrrFrrrr create_taskr-_maybe_auto_subscriberprrcr.rr_r)r|rrrrrrr7rrrr_inherit_workspacer#rr$r%r&r(rgoal_bool_errorr)r>rErf _self_tid _self_tasknew_tidnew_taskr*rs r_handle_creater3Bs5 HHW  E /E ((**/-...xx ##H   K    88F  Dhhy!!'RG XXh   B2:>>/#B#BF,''N2:>>:M+N+NJxx ##HXX.//NXX.//N)$$>(>(>J'4/JNd4J"(x88FJ&*%%%hh011O((#899XX.//<9N XXh  F&# *VdE]"C"C Pf9N P P   "1{!C!CI+/***XX.//N'3) ge} - -  OtG}}7M O O    HHW  E71%(((D0 " ?JNN+?@@ ?!#T9!=!=J!-*2K-)3)B)3)B&-*2G-)3)>Jnn%jj&&((Xg*2*>XA">22-% /+6+,,,<@#+9+EC'''4">22:>>*:;;Gx%1%G4{{411H.tW==J*2``; the TUI notification poller (``tui_gateway/server.py``) reads ``kanban_notify_subs`` for these rows and posts the completion message into the running session. - **CLI / cron / test / unattached**: no persistent delivery channel, no-op. Failure mode: any exception inside the function is logged at WARNING with the offending exception + diagnostic env vars and swallowed. We never want a notification bookkeeping failure to fail the kanban_create that the agent is mid-conversation about. rauto_subscribe_on_createTrzFrr)get_session_envHERMES_SESSION_PLATFORMHERMES_SESSION_CHAT_IDHERMES_SESSION_KEYtuiHERMES_SESSION_THREAD_IDNHERMES_SESSION_USER_IDHERMES_SESSION_PROFILErr@)r(platformchat_id thread_iduser_idnotifier_profilez9_maybe_auto_subscribe failed: %r (platform=%r key_set=%r))r r rgateway.session_contextr6rrrrCrAadd_notify_subr_rr) rfr(rr>r?r6 session_keyr@rArB_kb_excs rr,r,sL mmsH&@$OOO 5       HG/;;;;;;"?#>"6;;  uH!G#O$>CCKt !/":B??G4 O4b 9 9 0z~~.//  0/////  'w-    t  G (DMM   uuuuu s+!& 33AC< A-C<< D;*D66D;c td}|r|S|d}|stdStt |}|r|S|d} t |\}} ||t |}|s'td|d|Stt |d |S#|wxYw#t$r} td | cYd } ~ Sd } ~ wt$r6} t d td | cYd } ~ Sd } ~ wwxYw) z(Transition a blocked task back to ready.kanban_unblockr(ztask_id is requiredr>rBzcould not unblock z (not blocked or unknown)ready)r(rzkanban_unblock: Nzkanban_unblock failed) rrr r=r)rF unblock_taskrcrpr.rr_r) r|rrr:rr>rErfrmrs r_handle_unblockrLs &'7 8 8E  ((9  C 1/00023s88<rB)rNrOz kanban_link: Nzkanban_link failed) rr rF link_tasksrprcr.rr_r)r|rrNrOr>rErfrs r _handle_linkrQ8sR%%Ixx ##H FHFDEEE HHW  E /%(((D  MM$)hM G G GX>>> JJLLLLDJJLLLL ///-!--........ ///-...-!--......../sHB>((B%B>%B;;B>> D"CD" D",+DD"D"zrTask id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on).uXKanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call.dict[str, str]cdtdS)zSchema fragment for the optional ``board`` parameter. Centralised so a future tweak to the description / validation hint only has to land in one place. stringr description) _DESC_BOARDrrr_board_schema_proprXas [ 9 99r kanban_showuORead a task's full state — title, body, assignee, parent task handoffs, your prior attempts on this task if any, comments, and recent events. Use this to (re)orient yourself before starting work, especially on retries. The response includes a pre-formatted ``worker_context`` string suitable for inclusion verbatim in your reasoning.objectrTrU)r(r>)r propertiesrequired)r}rV parametersruList Kanban task summaries so an orchestrator profile can discover work to route. Supports the same core filters as the CLI: assignee, status, tenant, include_archived, and limit. Returns compact rows with ids, title, status, assignee, priority, parent/child ids, and counts. Bounded to 50 rows by default, 200 max, with truncation metadata. Also recomputes ready tasks before listing, matching the CLI. Orchestrator-only — dispatcher-spawned task workers never see this tool.z!Optional assignee/profile filter.)r#todorJr'rrarchivedzOptional task status filter.)renumrVz)Optional tenant/project namespace filter.booleanz*Include archived tasks. Defaults to false.integerz6Optional maximum rows to return (default 50, max 200).)rrrrrr>kanban_completeuhMark your current task done with a structured handoff for downstream workers and humans. Prefer ``summary`` for a human-readable 1-3 sentence description of what you did; put machine-readable facts in ``metadata`` (changed_files, tests_run, decisions, findings, etc). At least one of ``summary`` or ``result`` is required. If you created new tasks via ``kanban_create`` during this run, list their ids in ``created_cards`` — the kernel verifies them so phantom references are caught before they leak into downstream automation. If you produced deliverable files (charts, PDFs, spreadsheets, generated images), list their absolute paths in ``artifacts`` — the gateway notifier will upload them as native attachments to the human who subscribed to the task, so the deliverable lands in their chat alongside the summary instead of being a path they have to fetch by hand.zrHuman-readable handoff, 1-3 sentences. Appears in Run History on the dashboard and in downstream workers' context.uFree-form dict of structured facts about this attempt — {"changed_files": [...], "tests_run": 12, "findings": [...]}. Surfaced to downstream workers alongside ``summary``.zShort result log line (legacy field, maps to task.result). Use ``summary`` instead when possible; this exists for compatibility with callers that still set --result on the CLI.arrayruOptional structured manifest of task ids you created via ``kanban_create`` during this run. The kernel verifies each id exists and was created by this worker's profile; any phantom id blocks the completion with an error listing what went wrong (auditable in the task's events). Only list ids you got back from a successful ``kanban_create`` call — do not invent or remember ids from prose. Omit the field if you did not create any cards.)ritemsrVu1Optional list of absolute paths to deliverable files you produced during this run — generated charts, PDFs, spreadsheets, images, archives. Examples: ["/tmp/q3-revenue.png", "/tmp/report.pdf"]. The gateway notifier uploads each path as a native attachment to the subscribed chat (images embed inline, everything else uploads as a file) so the deliverable lands with the completion notification. Skip intermediate scratch files and references that are not the deliverable. The path must exist on disk when the notifier runs; missing files are silently skipped.)r(rr1rrrr> kanban_blockuqStop work on this task and route it according to WHY you're stuck. Set ``kind`` to say which: 'dependency' (waiting on another task — goes to todo and auto-resumes when that task finishes, no human needed), 'needs_input' (you need a human decision/answer), 'capability' (a hard wall: no access, missing credentials, an action no agent can do), or 'transient' (a flaky failure that may clear). ``reason`` is shown to the human on the board. If a task keeps getting unblocked and re-blocked for the same reason, it is auto-escalated to triage. Use for genuine blockers only — don't block on things you can resolve yourself.zWhat you need answered or what stopped you, in one or two sentences. Don't paste the whole conversation; the human has the board and can ask follow-ups via comments.)rGrH capability transientzWhy you're blocked. 'dependency' waits in todo and resumes automatically; the others surface to a human. Omit only if none apply.)r(rrr>rkanban_heartbeatuSignal that you're still alive during a long operation (training, encoding, large crawls). Call every few minutes so humans see liveness separately from PID checks. Pure side effect — no work changes.zHOptional short note describing current progress. Shown in the event log.)r(rYr>kanban_commentuAppend a comment to a task's thread. Use for durable notes that should outlive this run (questions for the next worker, partial findings, rationale). Ephemeral reasoning doesn't belong here — use your normal response instead.uWTask id. Required (may be your own task or another's — comment threads are per-task).z Markdown-supported comment body.)r(rr>r kanban_createucCreate a new kanban task, optionally as a child of the current one (pass the current task id in ``parents``). Used by orchestrator workers to fan out — decompose work into child tasks with specific assignees, link them into a pipeline, then complete your own task. The dispatcher picks up the new tasks on its next tick and spawns the assigned profiles.rzShort task title (required).ruProfile name that should execute this task (e.g. 'researcher-a', 'reviewer', 'writer'). Required — tasks without an assignee are never dispatched.zkOpening post: full spec, acceptance criteria, links. The assigned worker reads this as part of its context.rzParent task ids. The new task stays in 'todo' until every parent reaches 'done'; then it auto-promotes to 'ready'. Typical fan-in: list all the researcher task ids when creating a synthesizer task.rzUOptional namespace for multi-project isolation. Defaults to HERMES_TENANT env if set.rzZDispatcher tiebreaker. Higher = picked sooner when multiple ready tasks share an assignee.r)r"dirworktreezWorkspace flavor: 'scratch' (fresh tmp dir, default), 'dir' (shared directory, requires absolute workspace_path), 'worktree' (git worktree).rzYAbsolute path for 'dir' or 'worktree' workspace. Relative paths are rejected at dispatch.r!zOptional project id or slug to link the task to. When set, the task becomes a git worktree under the project's primary repo with a deterministic branch (project slug + task id), instead of a random branch.r#uIf true, task lands in 'triage' instead of 'todo' — a specifier profile is expected to flesh out the body before work starts.r$zIf a non-archived task with this key already exists, return that task's id instead of creating a duplicate. Useful for retry-safe automation.r%zxPer-task runtime cap. When exceeded, the dispatcher SIGTERMs the worker and re-queues the task with outcome='timed_out'.r&r'rzInitial card status. Use 'blocked' for tasks that require immediate human ops (R3 gate) to skip the brief running-to-blocked transition. Defaults to 'running', which preserves the usual dispatch path.r(u:Skill names to force-load into the dispatched worker. The kanban lifecycle is already injected automatically; use this to pin a task to a specialist context — e.g. ['translation'] for a translation task, ['github-code-review'] for a reviewer task. The names must match skills installed on the assignee's profile.raRun the dispatched worker in a goal loop. When true, after each turn an auxiliary judge checks the worker's response against this card's title/body; if the work isn't done and budget remains, the worker keeps going in the same session until the judge agrees it's complete (or the goal-turn budget is exhausted, which blocks the task for human review). Use this for open-ended cards where one shot rarely finishes the work. Defaults to false (classic single-shot worker).r)zTurn budget for goal_mode workers. Caps how many continuation turns the worker may take before the task is blocked for review. Ignored unless goal_mode is true. Defaults to the goal-engine default (20).rIuMove a blocked Kanban task back to ready. Orchestrator-only — only profiles with the kanban toolset can unblock routed work; dispatcher-spawned task workers never see this tool.z#Blocked task id to return to ready. kanban_linkuAdd a parent→child dependency edge after both tasks already exist. The child won't promote to 'ready' until all parents are 'done'. Cycles and self-links are rejected.zParent task id.zChild task id.)rNrOr>rNrOru📋)r}toolsetschemahandlercheck_fnemojiu✔u⏸u💓u💬u➕u▶u🔗)rr)r#r$rr$)r(r)rr*)r(r)r1r2rr2)r:r)rr$)N)r>r$)rkrrr))rqrrr$)r|r6r}r)r{r)rr)rr$)rr)r|r6rr))rfrr(r)rr)rrR)C__doc__ __future__rrnloggingrtypingrr agent.redactrhermes_cli.goalsrtools.registryrr rr r getLoggerrr_rrrr r"r'r0r9r=rF frozensetrrOr]rQ__annotations__rjrpryrrrrrr rrrr3r,rLrQ_DESC_TASK_ID_DEFAULTrWrXKANBAN_SHOW_SCHEMAKANBAN_LIST_SCHEMAKANBAN_COMPLETE_SCHEMAKANBAN_BLOCK_SCHEMAKANBAN_HEARTBEAT_SCHEMAKANBAN_COMMENT_SCHEMAKANBAN_CREATE_SCHEMAKANBAN_UNBLOCK_SCHEMAKANBAN_LINK_SCHEMAregisterrrrrsa 8#"""""  ......''''''////////22222222  8 $ $    ))))" ) ) ) )$        @ ' ' ' ' '"+L-+H!I!I....T(,$&)))))8888v....?D B B B B B B$>I/I/I/I/X:/:/:/:/za3a3a3a3HK0K0K0K0\04040404f"2"2"2"2Jt1t1t1t1n````F22228////68  ::::  &!4('))     0  !B ! > !J "K!! "W('))3  6;++\  >"!4 !(!5!B  (+ 0 "  (+ , &('))EC C HMGG'[[|  4!4 !O!PPP/ ('))-  0J5**Z  & !4 !.('))   !:  < !C!A('))   '!:  CO  =O  " O   #O ,  (+(  -O B  <CO P !CQO ^  666K _O p  ?qO ~  <O P !3QO `  E  aO p "!5$$qO @  "I.J  AO T  (+*  UO n !L  oO J !FKO \ ''))]O `j)eSS^^B  ? !D('))   K  *  : "*;LMM"*;KLL''))  !*-.            ,     !              "                     ,         r