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 and returns a Job that stays INPUT_REQUIRED until the human answers (Job COMPLETE with the response), rejects, or the request expires (Job FAILED). Asks are typed: text (free text), approval (yes/no), choice (pick one option), checkboxes (pick many). Approval asks and options may offer capability grants ({with, can, exp?}) that are issued ONLY if the human makes that choice and explicitly echoes the grant. Grant exp is unix seconds; omit it for the venue's 7-day default or set it explicitly to null to request no expiry. A venue may configure a finite HITL grant ceiling and rejects excessive offers before delivery. Omit user to ask your own owner. There is no framework timeout — set timeout (seconds) for time-sensitive asks and handle the FAILED outcome. |
| 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. |