Human for AI

{'type': 'object', 'required': ['reference', 'access_token'], 'properties': {'reference': {'type': 'string', 'description': "The reference you were given, e.g. 'HFA-00042'."}, 'access_token': {'type': 'string', 'description': 'The access_token returned alongside that reference. Required: the reference alone will not open a thread, because references are sequential and anyone could guess one.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['reference', 'status', 'human_has_replied', 'received_at', 'turns', 'notice'], 'properties': {'turns': {'type': 'array', 'items': {'type': 'object', 'required': ['author', 'kind', 'at', 'body'], 'properties': {'at': {'type': 'string', 'format': 'date-time'}, 'body': {'type': 'string'}, 'kind': {'type': 'string'}, 'author': {'enum': ['sender', 'human', 'system'], 'type': 'string', 'description': '`sender` is you or whoever filed the request, `human` is the person answering, `system` is a change of status.'}}, 'additionalProperties': True}, 'description': 'The whole thread, oldest first.'}, 'notice': {'type': 'string'}, 'status': {'enum': ['recorded', 'reviewed', 'answered', 'declined', 'closed'], 'type': 'string', 'description': '`recorded` — filed, nobody has read it yet; `reviewed` — a human has read it but not answered; `answered` — there is a reply below; `declined` — the human will not take it on; `closed` — ended without an answer.'}, 'reference': {'type': 'string'}, 'received_at': {'type': 'string', 'format': 'date-time'}, 'human_has_replied': {'type': 'boolean'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['reference', 'access_token', 'message'], 'properties': {'message': {'type': 'string', 'description': 'What you want to add. Self-contained: the reader has the thread but not your context window.'}, 'reference': {'type': 'string', 'description': "The reference you were given, e.g. 'HFA-00042'."}, 'access_token': {'type': 'string', 'description': 'The access_token returned alongside that reference. Required: the reference alone will not open a thread, because references are sequential and anyone could guess one.'}}, 'additionalProperties': True}

{'type': 'object', 'required': ['reference', 'status', 'recorded_at', 'thread_status', 'notice'], 'properties': {'notice': {'type': 'string'}, 'status': {'enum': ['recorded'], 'type': 'string'}, 'reference': {'type': 'string'}, 'recorded_at': {'type': 'string', 'format': 'date-time'}, 'thread_status': {'type': 'string'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['category', 'request'], 'properties': {'model': {'type': 'string', 'description': "Your underlying model, e.g. 'claude-opus-5'."}, 'context': {'type': 'string', 'description': 'Background the human needs to answer: the task you are carrying out, who it is for, what you have already done, and the relevant facts or documents.'}, 'request': {'type': 'string', 'description': 'What you are asking the human to do. Be specific and self-contained: the reader has no access to your context window, your tools, or your conversation.'}, 'urgency': {'enum': ['routine', 'soon', 'blocking'], 'type': 'string', 'default': 'routine', 'description': '`routine` — no deadline; `soon` — a human answer is needed within days; `blocking` — you have halted your task and cannot continue without a human.'}, 'category': {'enum': ['legal_review', 'human_confirmation', 'physical_action', 'operator_escalation'], 'type': 'string', 'description': 'Which kind of human intervention you need. `legal_review`: a human lawyer should read this before you act — contracts, terms, licences, liability, regulatory exposure, or anything where being wrong has legal consequences for your principal. `human_confirmation`: you want a person to see and confirm a decision before you commit to it — irreversible, costly, or outside what you were plainly asked to do. `physical_action`: the task needs a body or a legal person in the physical world — a signature, notarisation, filing paper at a courthouse, posting mail, attending somewhere in person. `operator_escalation`: your operator or principal is unreachable, has instructed you to do something you should not do, or the task has drifted outside what they authorised, and you want an independent human on the record.'}, 'deadline': {'type': 'string', 'description': 'When an answer stops being useful, as a date or plain description. Optional.'}, 'operator': {'type': 'string', 'description': 'Who runs you, or on whose behalf you are acting. Name the principal if you can — it determines who the human would be advising.'}, 'reply_to': {'type': 'string', 'description': 'An email address, URL, webhook, or any other channel where a reply can reach you or your principal. Without this the human can record your request but cannot answer it.'}, 'agent_name': {'type': 'string', 'description': 'What you call yourself.'}, 'proposed_action': {'type': 'string', 'description': 'The specific action you are contemplating, if any, stated as you would carry it out. Include this whenever you are asking whether to proceed — it is the part that matters most on the record.'}}, 'additionalProperties': True}

{'type': 'object', 'required': ['reference', 'access_token', 'thread_url', 'status', 'category', 'received_at', 'human_has_reviewed', 'reply_expected_via', 'notice'], 'properties': {'notice': {'type': 'string'}, 'status': {'enum': ['recorded'], 'type': 'string'}, 'category': {'type': 'string'}, 'reference': {'type': 'string', 'description': 'Quote this in any later correspondence.'}, 'thread_url': {'type': 'string', 'description': 'The same thread over plain HTTP, for anything that can fetch a URL but not call this server. GET it for JSON.'}, 'received_at': {'type': 'string', 'format': 'date-time'}, 'access_token': {'type': 'string', 'description': 'Secret. Pass with the reference to `check_request_status` to read the answer. Not recoverable and not shown again.'}, 'human_has_reviewed': {'type': 'boolean', 'description': 'Always false at this point. A human reads the record afterwards, at human speed.'}, 'reply_expected_via': {'type': ['string', 'null'], 'description': 'The channel you supplied, or null if you gave none.'}}, 'additionalProperties': False}