jh j UdZddlmZddlZddlZddlZddlmZmZddl m Z m Z ej e ZdZdZdd Zdd Zdd ZddZddZddZddZdddZdZdaded<ddZdd"Zdd$Zd%d&dd+Zdd-Z dd/Z!dd0Z"dd1Z#dd2Z$dd3Z%dd4Z&dd5Z'dd6Z(dd7Z)dd8Z*d9Z+d:Z,dd<Z-d=d>d?d@e+dAe-dBgdCdDZ.dEdFd?d@dGdAd@gdHdIdJd@dKdAdLdMdAdNdOdAe-dPgdCdDZ/dQdRd?d@e+dAd@dSdAd?dTdAd@dUdAdVdWd@idXdYdVdWd@idZdYe-d[gdCdDZ0d\d]d?d@e+dAd@d^dAe-d_d`gdCdDZ1dadbd?d@e+dAd@dcdAe-ddgdCdDZ2dedfd?d@dgdAd@dhdAe-diddjgdCdDZ3dkdld?idmd@dndAdod@dpdAdjd@dqdAdrdVdWd@idsdYdtd@dudAdvdNdwdAdxd@gdydzdJd{d@d|dAd}dLd~dAdd@ddAddNddAdd@ddgddJddVdWd@iddYddLddAddNddAde-dmdogdCdDZ4ddd?d@ddAe-dBdgdCdDZ5ddd?d@ddAd@ddAe-dddgdCdDZ6e j7d=de.e"ede j7dEde/e#ede j7dQde0e$ede j7d\de1e%ede j7dade2e&ede j7dede3e'ede j7dkde4e(ede j7dde5e)ede j7dde6e*eddS)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)registry tool_error2returnboolcz ddlm}|}|dg}d|vS#t$rYdSwxYw)Nr) load_configtoolsetskanbanF)hermes_cli.configr get Exception)r cfgrs 7/home/ubuntu/.hermes/hermes-agent/tools/kanban_tools.py_profile_has_kanban_toolsetr1sd111111kmm77: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>s, 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_moderOs, 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$as-  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_idr-ist 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%r. session_idstampeds r_stamp_worker_session_metadatar6vse 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)r7r#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_clir=connect)r;kbs r_connectrBs/+***** rzzz&& &&rgN@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 failedT)exc_infor)noteexpected_run_idz'auto-heartbeat: heartbeat_worker failedzauto-heartbeat: bridge failed)rrrtime monotonicrD$_AUTO_HEARTBEAT_MIN_INTERVAL_SECONDSrBheartbeat_claimrloggerdebugr* TypeErrorr+heartbeat_workerclose)r7_timenowrAconn claim_lock run_id_rawrun_ids r!heartbeat_current_worker_from_envr\sN, *..- . .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)r]s r_okrbs :tT,V, - --rvaluec|dSt|}|r|dvrdS|S)zANormalize CLI-compatible assignee sentinels for the tool surface.N>-nonenull)r&striplower)rctexts r_normalize_profilerk sH }t u::    D 4::<<#888t KrF)defaultargsr3namerlc||}||dfSt|tr|dfSt|}|dvrdS|dvrdS||dfS)N>1yestrue)TN>0nofalse)FNz$ must be a boolean or 'true'/'false')r isinstancer r&rhri)rmrnrlrcrjs r_parse_bool_argrws 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.Nr9)rxs r_require_orchestrator_toolrz#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|d|dt!|dt!|iS)z+Compact task shape for board-listing tools.idtitleassigneestatusprioritytenantworkspace_kindworkspace_path created_by created_at started_at completed_atcurrent_run_idmodel_overrideparentschildren parent_count child_count) parent_idsr} child_idsr~rrrrrrrrrrrrlen)rArXtaskrrs r_task_summary_dictr5s<mmD$'**G||D$'**H  dg   DM  $+   DM   $+   $-  $-  do  do  do  )  $-  $-  7  H! " G # $ s8}}%  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;r>Nztask z not foundcid|jd|jd|jd|jd|jd|jd|jd|jd |jd |j d |j d |j d |j d|j d|jd|jS)Nr}r~bodyrrrrrrrrrrresultrr)r}r~rrrrrrrrrrrrrr)ts r _task_dictz _handle_show.._task_dicths !$  ' 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 r}profileroutcomesummaryerrorr.rended_atr)rs r _run_dictz_handle_show.._run_dictws:$19h19 y17 ! "#,AJ rc8g|]}|j|j|jdS)authorrrr.0cs r z _handle_show..s? !x#$<11rcDg|]}|j|j|j|jdS)kindpayloadrr[r)res rrz _handle_show..sEV #$<18EEric&g|] }|Srr)rrrs rrz _handle_show..s!444!1444r)rrrcommentseventsrunsworker_contextz kanban_show: zkanban_show failed)r$rrrBget_taskrU list_comments list_events list_runsrrr`rabuild_worker_contextr+rrQ exception)rmkwr7r;rArXrrrrrrrrrs @r _handle_showrSs 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;r>)rrrrrc2g|]}t|Sr)r)rrrXrAs rrz _handle_list..s&IIIa,Rq99IIIr)taskscountr truncated next_limitpromotedz kanban_list: zkanban_list failed)rzrrwrKANBAN_LIST_DEFAULT_LIMITr*rSr+KANBAN_LIST_MAX_LIMITrBrecompute_ready list_tasksrr`raminrUrrQr)rmrguardrrrr bool_errorrr;rrowsrrrrXrAs @@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}|d}|d}|dt |t r|g}t |t tfs$td t|j Sd |D}|Vt |t r|g}t |t tfs$td t|j Sd |D}|r|i}n9t |ts$td t|j S|d} t | t tfr|g} t} t | |zD]S} t |  } | r.| | vr*| | | | T| |d<n||d<|s|stdS|9t |ts$td t|j St||}|d} t!|\}} |||||||t%|}nV#|j$rI}tdd|jdcYd}~|Sd}~wwxYw|s'td|d|S|||}t1||r|jnd|S#|wxYw#t4$r}td|cYd}~Sd}~wt6$r6}t8dtd|cYd}~Sd}~wwxYw)z5Mark the current task done with a structured handoff.r%rrr.r created_cards artifactsNz.created_cards must be a list of task ids, got cg|]D}t|#t|ESrr&rhrs 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;r>)rrr.rrLzfkanban_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%r[zkanban_complete: zkanban_complete failed)r$rrr:rvr&listtupletype__name__r3setrhaddappendr6rB complete_taskr-HallucinatedCardsErrorjoinphantomrU latest_runrbr}r+rrQr)rmrr7 ownership_errrr.rrrexistingmergedseenitemsr;rArXr_hall_errrunrs r_handle_completers3 488I.. / /C   H   3377Mhhy!!Gxx ##H XXh  FHH_--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<8)L"!O%" M5,*M0M5O%O>0M55O% O>!/O%O>%O;;O>> Q"PQ" Q",+QQ"Q"c t|d}|stdSt|}|r|S|d}|r!t |stdS|d} t |\}} ||||t|}|s'td|d | S| ||} t|| r| j nd | S#| wxYw#t$r} td | cYd } ~ Sd } ~ wt$r6} td td | cYd } ~ Sd } ~ wwxYw)z?Transition the task to blocked with a reason a human will read.r%rreasonu2reason is required — explain what input you needr;r>)rrLzcould not block z% (unknown id or not in running/ready)Nrzkanban_block: zkanban_block failed)r$rrr:r&rhrB block_taskr-rUrrbr}r+rrQr) rmrr7rrr;rArXr_rrs r _handle_blockrVs 488I.. / /C   H   3377M XXh  F PV**,,PNOOO HHW  E0%(((D c .s 3 3B  !&s&&& JJLLLL--c**CsS+B366dCCC JJLLLLDJJLLLL 000.1..//////// 000.///.1..////////0sT$E$8:E 2E$/E 6E$ E!!E$$ G.F?G G+G=GGc `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%rrKr;r>rFrGrJzcould not heartbeat z (unknown id or not running))r%zkanban_heartbeat: Nzkanban_heartbeat failed)r$rrr:rBrrrPrTr-rUrbr+rrQr) rmrr7rrKr;rArXrYr_rs r_handle_heartbeatr|s 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}|stdS|d}|r!t|stdStjdpd}|d} t |\}} ||||t| }t|| | S#| wxYw#t$r} td | cYd } ~ Sd } ~ wt$r6} t d td | 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 requiredHERMES_PROFILEworkerr;r>)rr)r% comment_idzkanban_comment: Nzkanban_comment failed)rrr&rhrrrB add_commentrbrUr+rrQr) rmrr7rrr;rArXcidrs r_handle_commentrs ((9  C   B    88F  D .s4yy((.,---Z^^, - - 9F HHW  E 2%(((D ..s6D .JJCss333 JJLLLLDJJLLLL 2220Q0011111111 22201110Q00111111112sH%D96D/DDD F'D>8F> F +E<6F<Fc x |d}|r!t|stdS|d}|stdS|d}|dpg}|dptjd}|d ptjd }|d }|d } |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|\}} | rNtjd}|r-| ||}||jr|j} |j} ||t||t|t|||t#|ndt| | | ||t#|nd|||t#|ndt|tjdpd| }| ||}t%||r|jnd!|S#|wxYw#t*$r}td"|cYd}~Sd}~wt,$r6}t.d#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. r~ztitle is requiredruassignee is required — name the profile that should execute this task (the dispatcher will only spawn tasks with an assignee)rrr HERMES_TENANTr4r1rrrNscratchtriageidempotency_keymax_runtime_secondsinitial_statusrunningskillsz*skills must be a list of skill names, got goal_modegoal_max_turnsz(parents must be a list of task ids, got r;r>rrrr)r~rrrrrrrrrrrrrrrr4r%rzkanban_create: zkanban_create failed)rr&rhrrrrwrvrrrrrBrrr create_taskr*rbrrUr+rrQr)rmrr~rrrrr4rrr_inherit_workspacerrrrrrrgoal_bool_errorrr;rArX _self_tid _self_tasknew_tidnew_taskrs r_handle_creaters HHW  E /E ((**/-...xx ##H   K    88F  Dhhy!!'RG XXh   B2:>>/#B#BF,''N2:>>:M+N+NJxx ##HXX.//NXX.//N'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  E01%(((D) " CJNN+?@@ C!#T9!=!=J!-*2K-)3)B)3)Bnn%jj&&((Xg*2*>XA">22- /+6+,,,<@#+9+EC'''4">22:>>*:;;Gx%/%G2{{411H*2zcould not unblock z (not blocked or unknown)readyrzkanban_unblock: Nzkanban_unblock failed) rzrrr:r&rB unblock_taskrUrbr+rrQr) rmrrr7rr;rArXr_rs r_handle_unblockrBs &'7 8 8E  ((9  C 1/00023s88<)rrz kanban_link: Nzkanban_link failed) rrrB link_tasksrbrUr+rrQr)rmrrrr;rArXrs r _handle_linkr^sR%%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_propr s [ 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.objectrr)r%r;)r propertiesrequired)rnr 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.)rtodorrblockeddonearchivedzOptional task status filter.)renumrz)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.)ritemsru1Optional 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%rr.rrrr; kanban_blockuTransition the task to blocked because you need human input to proceed. ``reason`` will be shown to the human on the board and included in context when someone unblocks you. Use for genuine blockers only — don't block on things you can resolve yourself.zWhat you need answered, in one or two sentences. Don't paste the whole conversation; the human has the board and can ask follow-ups via comments.)r%rr;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%rKr;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.r~zShort 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)rdirworktreezWorkspace 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.ruIf true, task lands in 'triage' instead of 'todo' — a specifier profile is expected to flesh out the body before work starts.rzIf a non-archived task with this key already exists, return that task's id instead of creating a duplicate. Useful for retry-safe automation.rzxPer-task runtime cap. When exceeded, the dispatcher SIGTERMs the worker and re-queues the task with outcome='timed_out'.rrr'zInitial 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.ru4Skill names to force-load into the dispatched worker (in addition to the built-in kanban-worker skill). 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).rzTurn 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).ruMove 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.)rrr;rrru📋)rntoolsetschemahandlercheck_fnemojiu✔u⏸u💓u💬u➕u▶u🔗)r r )r r!r r!)r%r&r r')r%r&r.r/r r/)r7r&r r!)N)r;r!)r]rr r&)rcrr r!)rmr3rnr&rlr )rxr&r r!)r r{)rmr3r r&)r r)8__doc__ __future__rr`loggingrtypingrrtools.registryrr getLoggerrrQrrrrrr$r-r6r:rBrOrD__annotations__r\rbrkrwrzrrrrrrrrrr_DESC_TASK_ID_DEFAULTrr KANBAN_SHOW_SCHEMAKANBAN_LIST_SCHEMAKANBAN_COMPLETE_SCHEMAKANBAN_BLOCK_SCHEMAKANBAN_HEARTBEAT_SCHEMAKANBAN_COMMENT_SCHEMAKANBAN_CREATE_SCHEMAKANBAN_UNBLOCK_SCHEMAKANBAN_LINK_SCHEMAregisterrrrrNs 8#"""""  ////////  8 $ $    ))))" ) ) ) )$        @ ' ' ' ' 'H(,$&)))))8888v....?D B B B B B B$ !J "K!! "W('))3  6;++\  >"!4 !(!5!B  (+ 0 "  (+ , &('))EC C HMGG'[[|  !4 !E('))  J#>  & !4 !.('))   !:  < !C!A('))   '!:  CF  =F  " F   #F ,  (+(  -F B  <CF P !CQF ^  666K _F p  ?qF ~ !3F N  E  OF ^ "!5$$_F n  "I.J  oF B  (+*  CF \ !L  ]F x !FyF J ''))KF Nj)SJJUUp  ? !D('))   K  *  : "*;LMM"*;KLL''))  !*-.            ,     !              "                     ,         r