i3edZddlmZddlZddlZddlZddlmZmZddl m Z m Z ej e ZdadZdbd Zd ZdcdZdddZdddZdddZdddZdddZdddZdddZdZddddded igd!d"Zd#d$dded dd%d dd&d dd'd d(gd!d"Zd)d*dded dd+d d,d-gd!d"Zd.d/dded dd0d d1gd!d"Zd2d3ddd4d dd5d dd6d d7dd8gd!d"Zd9d:ddd;d ddd?did@dAddBd dCdDd dgdEdFdGddHd dIdJd ddKd dCdLd d>d?didMdAdN dOdPgd!d"Z dQdRdddSd ddTd dUdVdWgd!d"Z!e j"ddXeeedYZe j"d#dXeeed[Ze j"d)dXeeed\Ze j"d.dXeeed]Ze j"d2dXeeed^Ze j"d9dXe eed_Ze j"dQdXe!eed`ZdS)euKanban tools — structured tool-call surface for worker + orchestrator agents. These tools are only registered into the model's schema when the agent is running under the dispatcher (env var ``HERMES_KANBAN_TASK`` set). A normal ``hermes chat`` session sees **zero** kanban tools in its schema. 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 ONLY for the worker agent's handoff back to the kernel. ) annotationsN)AnyOptional)registry tool_errorreturnboolcZttjdS)a&Tools are available iff the current process has ``HERMES_KANBAN_TASK`` set in its env, which the dispatcher sets when spawning a worker. Humans running ``hermes chat`` see zero kanban tools. Workers spawned by the kanban dispatcher (gateway-embedded by default) see all seven. HERMES_KANBAN_TASK)r osenvironget7/home/ubuntu/.hermes/hermes-agent/tools/kanban_tools.py_check_kanban_moder*s!  344 5 55rarg Optional[str]cP|r|Stjd}|pdS)zGResolve ``task_id`` arg or fall back to the env var the dispatcher set.r N)r r r)renv_tids r_default_task_idr8s-  jnn122G ?drc:ddlm}||fS)zImport + connect lazily so the module imports cleanly in non-kanban contexts (e.g. test rigs that import every tool module).r) kanban_db) hermes_clirconnect)kbs r_connectr@s)+***** rzz|| rfieldsrstrc 2tjddi|S)NokT)jsondumps)rs r_okr$Gs :tT,V, - --rargsdictc  t|d}|stdS t\}} |||}|'td|d|S|||}|||}|||}| ||} | ||} d} d tj | || | d|Dd |d dD fd |D| ||d |S#|wxYw#t$r6} td td| cYd} ~ Sd} ~ wwxYw)zsRead a task's full state: task row, parents, children, comments, runs (attempt history), and the last N events.task_id:task_id is required (or set HERMES_KANBAN_TASK in the env)Nztask z not foundc|j|j|j|j|j|j|j|j|j|j |j |j |j |j |jdS)Nidtitlebodyassigneestatustenantpriorityworkspace_kindworkspace_path created_by created_at started_at completed_atresultcurrent_run_idr+)ts r _task_dictz _handle_show.._task_dictcsZ$!& ! ahhAJ&'&6&'&6"#,al"#,$%Nh&'&6   rc t|j|j|j|j|j|j|j|j|jd S)N r,profiler0outcomesummaryerrormetadatar7ended_atr>)rs r _run_dictz_handle_show.._run_dictqs:$19h19 y17 ! "#,AJ rc8g|]}|j|j|jdS)authorr.r6rH).0cs r z _handle_show..~s? !x#$<11rcDg|]}|j|j|j|jdS)kindpayloadr6run_idrN)rJes rrLz _handle_show..sEV #$<18EEric&g|] }|Srr)rJrErFs rrLz _handle_show..s!444!1444r)taskparentschildrencommentseventsrunsworker_contextzkanban_show failedz kanban_show: )rrrrget_taskclose list_comments list_events list_runs parent_ids child_idsr"r#build_worker_context Exceptionlogger exception)r%kwtidrconnrTrWrXrYrUrVr<rRrFs @r _handle_showriOs2 488I.. / /C   H   </::D7 ;;tS))D|!"9#"9"9"9::h JJLLLLg''c22H^^D#..F<<c**DmmD#..G||D#..H      :" 4(("$& $CDD\ 5444t444 #%"9"9$"D"D', JJLLLLDJJLLLL ///-...-!--......../sBF *E02F CE0F 0FF G +G>G G c nt|d}|stdS|d}|d}|d}|s|stdS|9t|ts$tdt |jS t\}} |||||| }|s'td |d | S| ||} t|| r| j nd | S#| wxYw#t$r6} td td| cYd} ~ Sd} ~ wwxYw)z5Mark the current task done with a structured handoff.r(r)rArCr9z4provide at least one of: summary (preferred), resultNz%metadata must be an object/dict, got )r9rArCzcould not complete z! (unknown id or already terminal)r(rQzkanban_complete failedzkanban_complete: )rrr isinstancer&type__name__r complete_taskr\ latest_runr$r,rcrdre) r%rfrgrArCr9rrhr!runrRs r_handle_completerrs 488I.. / /C   H   hhy!!Gxx ##H XXh  F  v  B   Jx$>$> MDNN4K M M   3::D !!cw"B !P#PPP JJLLLL--c**CsS+B366dCCC JJLLLLDJJLLLL 33312221a11222222223sBE4.EE4/EE4E11E44 F4>+F/)F4/F4c t|d}|stdS|d}|r!t|stdS t \}} ||||}|s'td|d|S|||}t||r|j nd |S#|wxYw#t$r6}t d td |cYd}~Sd}~wwxYw) z?Transition the task to blocked with a reason a human will read.r(r)reasonu2reason is required — explain what input you need)rtzcould not block z% (unknown id or not in running/ready)Nrkzkanban_block failedzkanban_block: )rrrrstripr block_taskr\rpr$r,rcrdre) r%rfrgrtrrhr!rqrRs r _handle_blockrws 488I.. / /C   H   XXh  F PV**,,PNOOO0::D tS88B !&s&&& JJLLLL--c**CsS+B366dCCC JJLLLLDJJLLLL 000.///.1..////////0sB<D,,D:D,/D>D,D))D,, E,6+E'!E,'E,c :t|d}|stdS|d} t\}} ||||}|s'td|d|St ||S#|wxYw#t$r6}t dtd |cYd }~Sd }~wwxYw) z>Signal that the worker is still alive during a long operation.r(r)note)ryzcould not heartbeat z (unknown id or not running))r(zkanban_heartbeat failedzkanban_heartbeat: N) rrrrheartbeat_workerr\r$rcrdre)r%rfrgryrrhr!rRs r_handle_heartbeatr{s; 488I.. / /C   H    88F  D 4::D $$T3T$::B !L3LLL JJLLLLs### JJLLLLDJJLLLL 44423332q22333333334sB C,CCC,CCC D$+DDDc |d}|stdS|d}|r!t|stdS|dp tjdpd} t \}} ||||t|}t|| | S#| wxYw#t$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)r.zbody is requiredrIHERMES_PROFILEworker)rIr.)r( comment_idzkanban_comment failedzkanban_comment: N) rrrrur r r add_commentr$r\rcrdre) r%rfrgr.rIrrhcidrRs r_handle_commentrs_ ((9  C   B    88F  D .s4yy((.,--- XXh   O2:>>2B#C#C OxF 2::D ..s6D .JJCss333 JJLLLLDJJLLLL 22201110Q00111111112s6%D76D-DDD E%+EEEc |d}|r!t|stdS|d}|stdS|d}|dpg}|dptjd}|d }|d pd }|d } t |d } |d} |d} |d} t| tr| g} | @t| ttfs$tdt| j St|tr|g}t|ttfs$tdt|j S t\}} | |t||t|t|||t|ndt|| | | | t| nd| tjdpd}|||}t!||r|jnd|S#|wxYw#t&$r6}t(dtd|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 requiredr/uassignee is required — name the profile that should execute this task (the dispatcher will only spawn tasks with an assignee)r.rUr1 HERMES_TENANTr2r3scratchr4triageidempotency_keymax_runtime_secondsskillsNz*skills must be a list of skill names, got z(parents must be a list of task ids, got rr}r~) r-r.r/rUr1r2r3r4rrrrr5)r(r0zkanban_create failedzkanban_create: )rrrurr r r rllisttuplermrnr create_taskintr[r$r0r\rcrdre)r%rfr-r/r.rUr1r2r3r4rrrrrrhnew_tidnew_taskrRs r_handle_creatersk HHW  E /E ((**/-...xx ##H   K    88F  Dhhy!!'RG XXh   B2:>>/#B#BFxx ##HXX.//<9NXX.//N $((8$$ % %Fhh011O((#899 XXh  F&# *VdE]"C"C Pf9N P P   '3) ge} - -  OtG}}7M O O   1::D nn%jj&&((Xg*2*>XA">22- /+6+,,,<@:>>*:;;Gx#%G&{{411H*2>> JJLLLLDJJLLLL ///-!--........ ///-...-!--......../sGB'(B9B'B$$B'' D 1CD  D +DD D zrTask id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on). 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.objectr(string)rm description)rm propertiesrequired)namer parameterskanban_completeaBMark 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.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.)r(rArCr9 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(rtrtkanban_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(rykanban_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.zKOverride author name. Defaults to the current profile (HERMES_PROFILE env).)r(r.rIr. 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.zShort task title (required).uProfile 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.arrayrmzParent 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.)rmitemsrzUOptional namespace for multi-project isolation. Defaults to HERMES_TENANT env if set.integerzZDispatcher tiebreaker. Higher = picked sooner when multiple ready tasks share an assignee.)rdirworktreezWorkspace flavor: 'scratch' (fresh tmp dir, default), 'dir' (shared directory, requires absolute workspace_path), 'worktree' (git worktree).)rmenumrzYAbsolute path for 'dir' or 'worktree' workspace. Relative paths are rejected at dispatch.booleanuIf true, task lands in 'triage' instead of 'todo' — a specifier profile is expected to flesh out the body before work starts.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.zxPer-task runtime cap. When exceeded, the dispatcher SIGTERMs the worker and re-queues the task with outcome='timed_out'.u4Skill 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.) r-r/r.rUr1r2r3r4rrrrr-r/ 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.rrrkanbanu📋)rtoolsetschemahandlercheck_fnemojiu✔u⏸u💓u💬u➕u🔗)rr )rrrr)rrrr)r%r&rr)#__doc__ __future__rr"loggingr typingrrtools.registryrr getLoggerrnrdrrrr$rirrrwr{rrr_DESC_TASK_ID_DEFAULTKANBAN_SHOW_SCHEMAKANBAN_COMPLETE_SCHEMAKANBAN_BLOCK_SCHEMAKANBAN_HEARTBEAT_SCHEMAKANBAN_COMMENT_SCHEMAKANBAN_CREATE_SCHEMAKANBAN_LINK_SCHEMAregisterrrrrs`2#"""""  ////////  8 $ $6666....D/D/D/D/N#3#3#3#3L000084444022220E1E1E1E1P////48  &  4   .  1!4 !(!5!B-  @E##..b  !4 !E   J!<  & !4 !.   8  < !C!A !4  ('-  F  C!= !"!#  (+(  !<"C!666K !?"3!E  "5$$  (+*  od d Jj)Ohhssl  : "*;LMM"*;KLL  !*- ,          !              "                        r