i}dZddlmZddlZddlZddlZddlmZmZddl m Z m Z ej e ZdfdZdgd ZdhdZdidZdZdjdZdkdZdkdZdkdZdkdZdkdZdkdZdkdZdZd d!d"d d#ed$igd%d&Zd'd(d"d#ed$d#d)d$d"d*d$d#d+d$d,d-d#id.d/d0gd%d&Zd1d2d"d#ed$d#d3d$d4d5gd%d&Zd6d7d"d#ed$d#d8d$d9gd%d&Z d:d;d"d#dd$d?d d@gd%d&Z!dAdBd"d#dCd$d#dDd$d#dEd$d,d-d#idFd/d#dGd$dHdId$d#gdJdKdLd#dMd$dNdOd$d#dPd$dHdQd$d,d-d#idRd/dS dTdUgd%d&Z"dVdWd"d#dXd$d#dYd$dZd[d\gd%d&Z#e j$d d]eeed^_e j$d'd]eeed`_e j$d1d]eeeda_e j$d6d]e eedb_e j$d:d]e!eedc_e j$dAd]e"eedd_e j$dVd]e#eede_dS)luKanban 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_errorreturnboolctjdrdS ddlm}|}|dg}d|vS#t $rYdSwxYw)aTools 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 all seven. HERMES_KANBAN_TASKTr) load_configtoolsetskanbanF)osenvirongethermes_cli.configr Exception)r cfgr s 7/home/piyush/.hermes/hermes-agent/tools/kanban_tools.py_check_kanban_moder*s z~~*++t 111111kmm77:r**8## uus)A AAarg Optional[str]cP|r|Stjd}|pdS)zGResolve ``task_id`` arg or fall back to the env var the dispatcher set.r N)rrr)renv_tids r_default_task_idrJs-  jnn122G ?dtask_idstr Optional[int]ctjd|krdStjd}|sdS t|S#t$rYdSwxYw)zDReturn this worker's dispatcher run id when it is scoped to task_id.r NHERMES_KANBAN_RUN_ID)rrrint ValueError)rraws r_worker_run_idr%Rst z~~*++w66t *../ 0 0C t3xx tts A A'&A'tidctjd}|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. r Nzworker 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&rs r_enforce_worker_task_ownershipr(_sp&jnn122G t g~~ @ @ @ @ @ @   4rc: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_clir*connect)kbs r_connectr.s)+***** rzz|| rfieldsrc 2tjddi|S)NokT)jsondumps)r/s r_okr4s :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.r: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_dictsZ$!& ! ahhAJ&'&6&'&6"#,al"#,$%Nh&'&6   rc t|j|j|j|j|j|j|j|j|jd S)N r;profiler?outcomesummaryerrormetadatarFended_atrM)rs r _run_dictz_handle_show.._run_dicts:$19h19 y17 ! "#,AJ rc8g|]}|j|j|jdS)authorr=rErW.0cs r z _handle_show..s? !x#$<11rcDg|]}|j|j|j|jdS)kindpayloadrErun_idr^)rZes rr\z _handle_show..sEV #$<18EEric&g|] }|Srd)rZrTrUs rr\z _handle_show..s!444!1444r)taskparentschildrencommentseventsrunsworker_contextzkanban_show failedz kanban_show: )rrrr.get_taskclose list_comments list_events list_runs parent_ids child_idsr2r3build_worker_contextrlogger exception)r5kwr&r-connrerhrirjrfrgrKrbrUs @r _handle_showrxs2 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 Xt|d}|stdSt|}|r|S|d}|d}|d}|d}|dt |t r|g}t |t tfs$tdt|j Sd |D}|s|std S|9t |ts$td t|j S t\}} | | |||||t| } nV#|j$rI} td d| jdcYd} ~ | Sd} ~ wwxYw| s'td|d| S|| |} t'|| r| jnd| S#| wxYw#t*$r6} t,dtd| cYd} ~ Sd} ~ wwxYw)z5Mark the current task done with a structured handoff.rr8rPrRrH created_cardsNz.created_cards must be a list of task ids, got cg|]D}t|#t|ESrd)rstriprYs rr\z$_handle_complete..sI    SVV\\^^ FFLLNN   rz4provide at least one of: summary (preferred), resultz%metadata must be an object/dict, got )rHrPrRrzexpected_run_idzfkanban_complete blocked: the following created_cards do not exist or were not created by this worker: z, zq. Either omit them, use only ids returned from successful kanban_create calls, or remove the created_cards field.zcould not complete z! (unknown id or already terminal)rrazkanban_complete failedzkanban_complete: )rrrr( isinstancerlisttupletype__name__r6r. complete_taskr%HallucinatedCardsErrorjoinphantomrm latest_runr4r;rrtru)r5rvr& ownership_errrPrRrHrzr-rwr1hall_errrunrbs r_handle_completers8 488I.. / /C   H   3377Mhhy!!Gxx ##H XXh  FHH_--M mS ) ) ,*OM-$77 2 &&/22    $1     v  B   Jx$>$> MDNN4K M M   3::D  %%#!7X"/$23$7$7 & ,   "Oyy!122OOO JJLLLL%  !P#PPP JJLLLL--c**CsS+B366dCCC JJLLLLDJJLLLL 33312221a11222222223srI)#)F I G *GG II)G  I7I) /I;I)I&&I)) J)3+J$J)$J)c  t|d}|stdSt|}|r|S|d}|r!t |stdS t \}} ||||t|}|s'td|d| S| ||}t||r|j nd | S#| wxYw#t$r6} td td | cYd} ~ Sd} ~ wwxYw) z?Transition the task to blocked with a reason a human will read.rr8reasonu2reason is required — explain what input you need)rr}zcould not block z% (unknown id or not in running/ready)Nr~zkanban_block failedzkanban_block: )rrrr(rr|r. block_taskr%rmrr4r;rrtru) r5rvr&rrr-rwr1rrbs r _handle_blockrs 488I.. / /C   H   3377M XXh  F PV**,,PNOOO0::D c .s 3 3B  !&s&&& JJLLLL--c**CsS+B366dCCC JJLLLLDJJLLLL 000.///.1..////////0sBE !:D4E 0/D4E 4E  E F +FF F c t|d}|stdSt|}|r|S|d} t \}} t jd}||||||||t|}|s'td|d| St| | S#| wxYw#t$r6} td td | 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. rr8noteHERMES_KANBAN_CLAIM_LOCK)claimer)rr}zcould not heartbeat z (unknown id or not running))rzkanban_heartbeat failedzkanban_heartbeat: N)rrrr(r.rrheartbeat_claimheartbeat_workerr%rmr4rrtru) r5rvr&rrr-rw claim_lockr1rbs r_handle_heartbeatr=s 488I.. / /C   H   3377M 88F  D4::D  (BCCJ   tS*  = = =$$ .s 3 3 %B  !L3LLL JJLLLLs### JJLLLLDJJLLLL 44423332q22333333334sCD2/A1D D25DD2D//D22 E2<+E-'E2-E2c |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.ruotask_id is required (use the current task id if that's what you mean — pulls from env but kept explicit here)r=zbody is requiredrXHERMES_PROFILEworker)rXr=)r comment_idzkanban_comment failedzkanban_comment: N) rrrr|rrr. add_commentr4rmrrtru) r5rvr&r=rXr-rwcidrbs r_handle_commentrms_ ((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=rfr@ HERMES_TENANTrArBscratchrCtriageidempotency_keymax_runtime_secondsskillsNz*skills must be a list of skill names, got z(parents must be a list of task ids, got rrr) r<r=r>rfr@rArBrCrrrrrD)rr?zkanban_create failedzkanban_create: )rrr|rrrr rrrrrr. create_taskr"rlr4r?rmrrtru)r5rvr<r>r=rfr@rArBrCrrrrr-rwnew_tidnew_taskrbs 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.objectstring)r description)r propertiesrequired)namer parameterskanban_completeuMark 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.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.)ritemsr)rrPrRrHrz 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.)rrrkanban_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.)rrkanban_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).)rr=rXr= 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.zParent 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.zUOptional 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).)renumrzYAbsolute 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=rfr@rArBrCrrrrr<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.rrrru📋)rtoolsetschemahandlercheck_fnemojiu✔u⏸u💓u💬u➕u🔗)rr )rrrr)rrrr)r&rrr)r/rrr)r5r6rr)%__doc__ __future__rr2loggingrtypingrrtools.registryrr getLoggerrrtrrr%r(r.r4rxrrrrrr_DESC_TASK_ID_DEFAULTKANBAN_SHOW_SCHEMAKANBAN_COMPLETE_SCHEMAKANBAN_BLOCK_SCHEMAKANBAN_HEARTBEAT_SCHEMAKANBAN_COMMENT_SCHEMAKANBAN_CREATE_SCHEMAKANBAN_LINK_SCHEMAregisterrdrrrs2#"""""  ////////  8 $ $@    @....D/D/D/D/NB3B3B3B3J 0 0 0 0F-4-4-4-4`22220E1E1E1E1P////48  &  4   .  !4 !(!5!B  (+ 0 ?/ / `e33BBJ  !4 !E   J!<  & !4 !.   8  < !C!A !4  ('-  F  C!= !"!#  (+(  !<"C!666K !?"3!E  "5$$  (+*  od d Jj)Ohhssl  : "*;LMM"*;KLL  !*- ,          !              "                        r