kanban_tools_schemas.py 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551
  1. """Tool schemas for tools.kanban_tools (model-facing; strings are byte-frozen)."""
  2. from __future__ import annotations
  3. from typing import Any
  4. from hermes_cli.kanban_workflow import ARCHIVED, DEFAULT_WORKFLOW
  5. _DESC_TASK_ID_DEFAULT = (
  6. "Task id. If omitted, defaults to HERMES_KANBAN_TASK from the env — the "
  7. "task the dispatcher spawned you to work on. That default only exists for "
  8. "a dispatcher-spawned worker; any other caller has no default and must "
  9. "pass an explicit task_id (use kanban_list to discover ids)."
  10. )
  11. _DESC_BOARD = (
  12. "Kanban board slug to target. When omitted, the call resolves the "
  13. "active board the usual way: HERMES_KANBAN_DB env → "
  14. "HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban "
  15. "home → 'default'. Pass an explicit slug only when the caller (e.g. "
  16. "a Telegram routing layer) needs to override the env-pinned active "
  17. "board for this one call."
  18. )
  19. def _prop(type_: str, description: str) -> dict[str, str]:
  20. return {"type": type_, "description": description}
  21. def _board_schema_prop() -> dict[str, str]:
  22. """Schema fragment for the optional ``board`` parameter (one place to tweak)."""
  23. return _prop("string", _DESC_BOARD)
  24. def _schema(name: str, description: str, properties: dict[str, Any], required: list[str]) -> dict[str, Any]:
  25. """Build a tool schema; every kanban tool takes an optional trailing ``board``."""
  26. return {
  27. "name": name,
  28. "description": description,
  29. "parameters": {
  30. "type": "object",
  31. "properties": {**properties, "board": _board_schema_prop()},
  32. "required": required,
  33. },
  34. }
  35. KANBAN_SHOW_SCHEMA = _schema(
  36. "kanban_show",
  37. (
  38. "Read a task's full state: body, assignee, parent handoffs, attempts, comments. "
  39. "It also carries the title and recent events. Use this to (re)orient yourself before "
  40. "starting work, especially on retries. The response includes a "
  41. "pre-formatted ``worker_context`` string suitable for inclusion "
  42. "verbatim in your reasoning. Outside a dispatcher-spawned worker "
  43. "there is no default task: a bare call returns a pointer to "
  44. "``kanban_list`` instead of task state."
  45. ),
  46. {
  47. "task_id": _prop("string", _DESC_TASK_ID_DEFAULT),
  48. },
  49. [],
  50. )
  51. KANBAN_LIST_SCHEMA = _schema(
  52. "kanban_list",
  53. (
  54. "List Kanban task summaries so an orchestrator can discover work to route. Supports the same core filters as the CLI: assignee, "
  55. "status, tenant, include_archived, and limit. Returns compact rows "
  56. "with ids, title, status, assignee, priority, parent/child ids, and "
  57. "counts. Bounded to 50 rows by default, 200 max, with truncation "
  58. "metadata. Also recomputes ready tasks before listing, matching the "
  59. "CLI. Orchestrator-only — dispatcher-spawned task workers never see "
  60. "this tool."
  61. ),
  62. {
  63. "assignee": _prop("string", "Optional assignee/profile filter."),
  64. "status": {
  65. "type": "string",
  66. "enum": [*DEFAULT_WORKFLOW.keys(), ARCHIVED],
  67. "description": "Optional task status filter.",
  68. },
  69. "tenant": _prop("string", "Optional tenant/project namespace filter."),
  70. "include_archived": _prop("boolean", "Include archived tasks. Defaults to false."),
  71. "limit": _prop("integer", "Optional maximum rows to return (default 50, max 200)."),
  72. },
  73. [],
  74. )
  75. KANBAN_COMPLETE_SCHEMA = _schema(
  76. "kanban_complete",
  77. (
  78. "Mark your current task done with a structured handoff for others. Prefer ``summary`` for a "
  79. "human-readable 1-3 sentence description of what you did; put "
  80. "machine-readable facts in ``metadata`` (changed_files, "
  81. "tests_run, decisions, findings, etc). At least one of "
  82. "``summary`` or ``result`` is required. If you created new "
  83. "tasks via ``kanban_create`` during this run, list their ids "
  84. "in ``created_cards`` — the kernel verifies them so phantom "
  85. "references are caught before they leak into downstream "
  86. "automation. If you produced deliverable files (charts, PDFs, "
  87. "spreadsheets, generated images), list their absolute paths "
  88. "in ``artifacts`` — the gateway notifier will upload them as "
  89. "native attachments to the human who subscribed to the task, "
  90. "so the deliverable lands in their chat alongside the summary "
  91. "instead of being a path they have to fetch by hand."
  92. ),
  93. {
  94. "task_id": _prop("string", _DESC_TASK_ID_DEFAULT),
  95. "summary": _prop("string", (
  96. "Human-readable handoff, 1-3 sentences. Appears in "
  97. "Run History on the dashboard and in downstream "
  98. "workers' context."
  99. )),
  100. "metadata": _prop("object", (
  101. "Free-form dict of structured facts about this "
  102. "attempt — {\"changed_files\": [...], \"tests_run\": 12, "
  103. "\"findings\": [...]}. Surfaced to downstream "
  104. "workers alongside ``summary``."
  105. )),
  106. "result": _prop("string", (
  107. "Short result log line (legacy field, maps to "
  108. "task.result). Use ``summary`` instead when "
  109. "possible; this exists for compatibility with "
  110. "callers that still set --result on the CLI."
  111. )),
  112. "created_cards": {
  113. "type": "array",
  114. "items": {"type": "string"},
  115. "description": (
  116. "Optional structured manifest of task ids you "
  117. "created via ``kanban_create`` during this run. "
  118. "The kernel verifies each id exists and was "
  119. "created by this worker's profile; any phantom "
  120. "id blocks the completion with an error listing "
  121. "what went wrong (auditable in the task's events). "
  122. "Only list ids you got back from a successful "
  123. "``kanban_create`` call — do not invent or "
  124. "remember ids from prose. Omit the field if you "
  125. "did not create any cards."
  126. ),
  127. },
  128. "artifacts": {
  129. "type": "array",
  130. "items": {"type": "string"},
  131. "description": (
  132. "Optional list of absolute paths to deliverable "
  133. "files you produced during this run — generated "
  134. "charts, PDFs, spreadsheets, images, archives. "
  135. "Examples: [\"~/.hermes/cache/scratch/q3-revenue.png\", "
  136. "\"~/.hermes/cache/scratch/report.pdf\"]. The gateway notifier "
  137. "uploads each path as a native attachment to the "
  138. "subscribed chat (images embed inline, everything "
  139. "else uploads as a file) so the deliverable "
  140. "lands with the completion notification. Skip "
  141. "intermediate scratch files and references that "
  142. "are not the deliverable. The path must exist "
  143. "on disk at completion. Files inside a managed scratch "
  144. "workspace are copied to durable task attachments before "
  145. "cleanup; a missing declared scratch artifact keeps the "
  146. "task in-flight so you can fix the path and retry."
  147. ),
  148. },
  149. },
  150. [],
  151. )
  152. KANBAN_BLOCK_SCHEMA = _schema(
  153. "kanban_block",
  154. (
  155. "Stop work on this task and route it according to WHY you're stuck. "
  156. "Set ``kind`` to say which: 'dependency' (waiting on another task — "
  157. "goes to todo and auto-resumes when that task finishes, no human "
  158. "needed), 'needs_input' (you need a human decision/answer), "
  159. "'capability' (a hard wall: no access, missing credentials, an action "
  160. "no agent can do), or 'transient' (a flaky failure that may clear). "
  161. "``reason`` is shown to the human on the board. If a task keeps "
  162. "getting unblocked and re-blocked for the same reason, it is "
  163. "auto-escalated to triage. Use for genuine blockers only — don't "
  164. "block on things you can resolve yourself."
  165. ),
  166. {
  167. "task_id": _prop("string", _DESC_TASK_ID_DEFAULT),
  168. "reason": _prop("string", (
  169. "What you need answered or what stopped you, in one or "
  170. "two sentences. Don't paste the whole conversation; the "
  171. "human has the board and can ask follow-ups via comments."
  172. )),
  173. "kind": {
  174. "type": "string",
  175. "enum": ["dependency", "needs_input", "capability", "transient"],
  176. "description": (
  177. "Why you're blocked. 'dependency' waits in todo and "
  178. "resumes automatically when an incomplete parent finishes; "
  179. "if no parent is open it is recorded as needs_input instead. "
  180. "The others surface to a human. Omit only if none apply."
  181. ),
  182. },
  183. },
  184. ["reason"],
  185. )
  186. KANBAN_SCHEDULE_SCHEMA = _schema(
  187. "kanban_schedule",
  188. (
  189. "Park your task as 'scheduled' while it waits for a time or external event. This ends the current run and makes the "
  190. "task non-dispatchable until an orchestrator unblocks it; it does not "
  191. "create a timer. Put any wake-up marker such as "
  192. "``SCHEDULED_UNTIL=<ISO8601>`` in ``reason``."
  193. ),
  194. {
  195. "task_id": _prop("string", _DESC_TASK_ID_DEFAULT),
  196. "reason": _prop("string", (
  197. "Optional reason or machine-readable wake-up marker recorded on "
  198. "the completed run and scheduled event."
  199. )),
  200. },
  201. [],
  202. )
  203. KANBAN_REQUEST_REVIEW_SCHEMA = _schema(
  204. "kanban_request_review",
  205. (
  206. "Hand a finished, self-verified task to a human or reviewer before it is done. Moves the task to the 'review' "
  207. "column and notifies the subscriber. Unlike ``kanban_block`` this is "
  208. "NOT a blocker — it never counts toward unblock-loop detection, so a "
  209. "task can cycle through review across follow-ups without ever being "
  210. "falsely escalated to triage. Use this instead of blocking with a "
  211. "free-form 'review-required:' reason."
  212. ),
  213. {
  214. "task_id": _prop("string", _DESC_TASK_ID_DEFAULT),
  215. "summary": _prop("string", (
  216. "What was implemented and how it was verified, in one or "
  217. "two sentences — shown to the reviewer. Don't paste "
  218. "the whole diff; the reviewer has the board and the PR."
  219. )),
  220. "reviewer": _prop("string", (
  221. "Optional reviewer profile. When provided, the task is "
  222. "reassigned to that profile before review dispatch."
  223. )),
  224. "metadata": {
  225. "type": "object",
  226. "description": (
  227. "Optional structured handoff facts for the reviewer, such "
  228. "as changed_files, tests_run, commit, or decisions."
  229. ),
  230. "additionalProperties": True,
  231. },
  232. "artifacts": {
  233. "type": "array",
  234. "items": {"type": "string"},
  235. "description": (
  236. "Optional list of absolute paths to deliverable "
  237. "files this handoff names — generated charts, "
  238. "PDFs, spreadsheets, images, archives. Examples: "
  239. "['~/.hermes/cache/scratch/q3-revenue.png', '~/.hermes/cache/scratch/report.pdf']. "
  240. "A review handoff is the last implementer "
  241. "transition, so the kernel copies these into the "
  242. "task's durable attachments before the reviewer's "
  243. "completion cleans the scratch workspace up, and "
  244. "the gateway notifier uploads them as native "
  245. "attachments to the subscribed chat. A missing "
  246. "declared scratch artifact keeps the task in place "
  247. "so you can fix the path and retry."
  248. ),
  249. },
  250. },
  251. ["summary"],
  252. )
  253. KANBAN_REQUEST_CHANGES_SCHEMA = _schema(
  254. "kanban_request_changes",
  255. (
  256. "Reviewer verdict: send the task back to its implementer with required changes. This closes the review "
  257. "run, reapplies parent dependency gating, and requeues the task without "
  258. "using block-loop accounting. Only use from a task claimed from the "
  259. "review column; use kanban_block only for a genuine external blocker."
  260. ),
  261. {
  262. "task_id": _prop("string", _DESC_TASK_ID_DEFAULT),
  263. "reason": _prop("string", (
  264. "Specific, actionable changes the implementer must make "
  265. "before requesting another review."
  266. )),
  267. },
  268. ["reason"],
  269. )
  270. KANBAN_HEARTBEAT_SCHEMA = _schema(
  271. "kanban_heartbeat",
  272. (
  273. "Signal you're still alive during a long operation (training, encoding, crawls). Call every few minutes so "
  274. "humans see liveness separately from PID checks. Pure side "
  275. "effect — no work changes."
  276. ),
  277. {
  278. "task_id": _prop("string", _DESC_TASK_ID_DEFAULT),
  279. "note": _prop("string", (
  280. "Optional short note describing current progress. "
  281. "Shown in the event log."
  282. )),
  283. },
  284. [],
  285. )
  286. KANBAN_COMMENT_SCHEMA = _schema(
  287. "kanban_comment",
  288. (
  289. "Append a comment to a task's thread. Use for durable notes "
  290. "that should outlive this run (questions for the next worker, "
  291. "partial findings, rationale). Ephemeral reasoning doesn't "
  292. "belong here — use your normal response instead."
  293. ),
  294. {
  295. "task_id": _prop("string", (
  296. "Task id. Required (may be your own task or "
  297. "another's — comment threads are per-task). Outside a "
  298. "dispatcher-spawned worker there is no default; use "
  299. "kanban_list to discover ids."
  300. )),
  301. "body": _prop("string", "Markdown-supported comment body."),
  302. },
  303. ["task_id", "body"],
  304. )
  305. KANBAN_ATTACH_SCHEMA = _schema(
  306. "kanban_attach",
  307. (
  308. "Attach a file to a task by passing its bytes inline (base64). "
  309. "Use for genuine file artifacts the next worker or a human should "
  310. "be able to download — generated reports, images, exports. The "
  311. "file is stored as a real attachment (not a comment link) under "
  312. "the task's attachments dir, capped at 25 MB. Prefer "
  313. "kanban_attach_url when you only have a URL."
  314. ),
  315. {
  316. "task_id": _prop("string", _DESC_TASK_ID_DEFAULT),
  317. "filename": _prop("string", (
  318. "File name to store it under (e.g. 'report.pdf'). "
  319. "Directory components are stripped; only the leaf is kept."
  320. )),
  321. "content_base64": {
  322. "type": "string",
  323. "description": "The file contents, base64-encoded. Max 25 MB decoded.",
  324. },
  325. "content_type": _prop("string", "Optional MIME type (e.g. 'application/pdf')."),
  326. },
  327. ["filename", "content_base64"],
  328. )
  329. KANBAN_ATTACH_URL_SCHEMA = _schema(
  330. "kanban_attach_url",
  331. (
  332. "Attach a file to a task by URL (Hermes downloads it server-side, max 25 MB). Use when "
  333. "you have a link rather than the bytes. Only http/https URLs are "
  334. "accepted."
  335. ),
  336. {
  337. "task_id": _prop("string", _DESC_TASK_ID_DEFAULT),
  338. "url": _prop("string", "http(s) URL to fetch and store."),
  339. "filename": _prop("string", (
  340. "Optional name to store it under. Defaults to the URL "
  341. "path's leaf component."
  342. )),
  343. "content_type": _prop("string", (
  344. "Optional MIME type override. Defaults to the "
  345. "Content-Type the server returns."
  346. )),
  347. },
  348. ["url"],
  349. )
  350. KANBAN_ATTACHMENTS_SCHEMA = _schema(
  351. "kanban_attachments",
  352. (
  353. "List a task's attached files, with the absolute on-disk path you can read. "
  354. "Rows carry id, filename, content_type, size and uploader."
  355. ),
  356. {
  357. "task_id": _prop("string", _DESC_TASK_ID_DEFAULT),
  358. },
  359. [],
  360. )
  361. KANBAN_CREATE_SCHEMA = _schema(
  362. "kanban_create",
  363. (
  364. "Create a kanban task, optionally a child of the current one (via ``parents``). Used by "
  365. "orchestrator workers to fan out — decompose work into child "
  366. "tasks with specific assignees, link them into a pipeline, "
  367. "then complete your own task. The dispatcher picks up the new "
  368. "tasks on its next tick and spawns the assigned profiles."
  369. ),
  370. {
  371. "title": _prop("string", "Short task title (required)."),
  372. "assignee": _prop("string", (
  373. "Profile name that should execute this task "
  374. "(e.g. 'researcher-a', 'reviewer', 'writer'). "
  375. "Required — tasks without an assignee are never "
  376. "dispatched."
  377. )),
  378. "body": _prop("string", (
  379. "Opening post: full spec, acceptance criteria, "
  380. "links. The assigned worker reads this as part of "
  381. "its context."
  382. )),
  383. "parents": {
  384. "type": "array",
  385. "items": {"type": "string"},
  386. "description": (
  387. "Parent task ids. The new task stays in 'todo' "
  388. "until every parent reaches 'done'; then it "
  389. "auto-promotes to 'ready'. Typical fan-in: list "
  390. "all the researcher task ids when creating a "
  391. "synthesizer task."
  392. ),
  393. },
  394. "tenant": _prop("string", (
  395. "Optional namespace for multi-project isolation. "
  396. "Defaults to HERMES_TENANT env if set."
  397. )),
  398. "priority": _prop("integer", (
  399. "Dispatcher tiebreaker. Higher = picked sooner "
  400. "when multiple ready tasks share an assignee."
  401. )),
  402. "workspace_kind": {
  403. "type": "string",
  404. "enum": ["scratch", "dir", "worktree"],
  405. "description": (
  406. "Workspace flavor: 'scratch' (fresh tmp dir, "
  407. "default), 'dir' (shared directory, requires "
  408. "absolute workspace_path), 'worktree' (git worktree)."
  409. ),
  410. },
  411. "workspace_path": _prop("string", (
  412. "Absolute path for 'dir' or 'worktree' workspace. "
  413. "Relative paths are rejected at dispatch."
  414. )),
  415. "project": _prop("string", (
  416. "Optional project id or slug to link the task to. When "
  417. "set, the task becomes a git worktree under the project's "
  418. "primary repo with a deterministic branch (project slug + "
  419. "task id), instead of a random branch."
  420. )),
  421. "triage": _prop("boolean", (
  422. "If true, task lands in 'triage' instead of 'todo' "
  423. "— a specifier profile is expected to flesh out "
  424. "the body before work starts."
  425. )),
  426. "idempotency_key": _prop("string", (
  427. "If a non-archived task with this key already "
  428. "exists, return that task's id instead of creating "
  429. "a duplicate. Useful for retry-safe automation."
  430. )),
  431. "max_runtime_seconds": _prop("integer", (
  432. "Per-task runtime cap. When exceeded, the "
  433. "dispatcher SIGTERMs the worker and re-queues the "
  434. "task with outcome='timed_out'."
  435. )),
  436. "initial_status": {
  437. "type": "string",
  438. "enum": ["running", "blocked"],
  439. "description": (
  440. "Initial card status. Use 'blocked' for tasks that "
  441. "require immediate human ops (R3 gate) to skip the "
  442. "brief running-to-blocked transition. Defaults to "
  443. "'running', which preserves the usual dispatch path."
  444. ),
  445. },
  446. "skills": {
  447. "type": "array",
  448. "items": {"type": "string"},
  449. "description": (
  450. "Skill names to force-load into the dispatched "
  451. "worker. The kanban lifecycle is already injected "
  452. "automatically; use this to pin a task to a specialist "
  453. "context — e.g. ['translation'] for a translation "
  454. "task, ['github-code-review'] for a reviewer task. "
  455. "The names must match skills installed on the "
  456. "assignee's profile."
  457. ),
  458. },
  459. "goal_mode": _prop("boolean", (
  460. "Run the dispatched worker in a goal loop. When true, "
  461. "after each turn an auxiliary judge checks the worker's "
  462. "response against this card's title/body; if the work "
  463. "isn't done and budget remains, the worker keeps going "
  464. "in the same session until the judge agrees it's "
  465. "complete (or the goal-turn budget is exhausted, which "
  466. "blocks the task for human review). Use this for "
  467. "open-ended cards where one shot rarely finishes the "
  468. "work. Defaults to false (classic single-shot worker)."
  469. )),
  470. "completion_contract": _prop("string", (
  471. "Declare at creation: local-only (default), OWNER/REPO for PR publication, or an exact GitHub PR URL. "
  472. "PR tasks cannot complete until repository-required exact-head CI passes. On publication pass metadata.published_pr."
  473. )),
  474. "goal_max_turns": _prop("integer", (
  475. "Turn budget for goal_mode workers. Caps how many "
  476. "continuation turns the worker may take before the task "
  477. "is blocked for review. Ignored unless goal_mode is "
  478. "true. Defaults to the goal-engine default (20)."
  479. )),
  480. "model": _prop("string", (
  481. "Pin the dispatched worker to this model instead of "
  482. "the assignee profile's configured model. Use the "
  483. "exact model name the target provider expects. Omit "
  484. "to use the profile default."
  485. )),
  486. "provider": _prop("string", (
  487. "Provider the 'model' belongs to (e.g. 'openrouter', "
  488. "'anthropic', 'nous'). Set this whenever the model "
  489. "is not from the assignee profile's configured "
  490. "provider — a model name alone is resolved against "
  491. "the profile's provider and will fail if it belongs "
  492. "to a different one. Requires 'model'."
  493. )),
  494. },
  495. ["title", "assignee"],
  496. )
  497. KANBAN_UNBLOCK_SCHEMA = _schema(
  498. "kanban_unblock",
  499. (
  500. "Unblock a Kanban task. It moves to ready when all parents are done, "
  501. "or todo while any parent remains open. Orchestrator-only — only "
  502. "profiles with the kanban toolset can unblock routed work; "
  503. "dispatcher-spawned task workers never see this tool."
  504. ),
  505. {
  506. "task_id": _prop("string", "Blocked task id to move to ready or parent-gated todo."),
  507. },
  508. ["task_id"],
  509. )
  510. KANBAN_LINK_SCHEMA = _schema(
  511. "kanban_link",
  512. (
  513. "Add a parent→child dependency edge after both tasks already "
  514. "exist. The child won't promote to 'ready' until all parents "
  515. "are 'done'. Cycles and self-links are rejected. A running child "
  516. "is rejected unless the active owning worker is linking its own "
  517. "card for a dependency handoff."
  518. ),
  519. {
  520. "parent_id": {"type": "string", "description": "Parent task id."},
  521. "child_id": {"type": "string", "description": "Child task id."},
  522. },
  523. ["parent_id", "child_id"],
  524. )