Human-in-the-Loop requests (COG-16): ask a human for decisions, approvals or information. Requests land as durable records in the target user's h/ inbox and are carried by a standard Job that completes with the response or fails on rejection or expiry. Approval asks and options may offer capability grants, issued only for choices the responder explicitly makes and echoes.
| Name: | hitl |
| Class: | covia.adapter.HITLAdapter |
This adapter provides 3 MCP tool(s) for AI agent integration:
| Tool Name | Description |
|---|---|
| hitl_list | List the HITL requests in your own h/ inbox — pending asks awaiting your decision and resolved ones. Filter by status: open, answered, rejected, expired, cancelled. Read a full request (asks, offered grants) with covia_read path=h/<id>. |
| hitl_request | Ask a human for decisions, approvals or information. Delivers a durable request into the target user's h/ inbox. From a sessioned agent tool call it returns the durable request id immediately with INPUT_REQUIRED; the answer, rejection or expiry later arrives as a verified message in the same session and wakes the agent. External callers receive the standard Job, which stays INPUT_REQUIRED until the human answers (Job COMPLETE), rejects, or the request expires (Job FAILED). Asks are typed: text, approval, choice, or checkboxes. Approval asks and options may offer capability grants ({with, can, exp?}) issued only when the human makes that choice and explicitly echoes the grant. Omit user to ask your own owner. Set timeout (seconds) for time-sensitive asks. |
| hitl_respond | Resolve a HITL request in YOUR OWN h/ inbox: answer it or reject it. Answering completes the requester's Job with your answers; rejecting fails it with your comment as the reason. If the request offered capability grants, echo the ones you approve in 'grants' — the venue issues exactly the intersection of what you echo and what your choices actually triggered (approved approval asks, selected options); echoing anything else fails the response. Answer forms: text → string, approval → boolean, choice → option id, checkboxes → array of option ids. |