Skip to content
Back to search

hitl-mcp

A production-ready, state-persistent MCP server for Human-in-the-Loop (HITL) interaction. Enables AI agents to suspend execution, ask structured questions to users, and resume contextually across sessions — friendly with ACP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zenlixai--hitl-mcp/badge.svg)](/listings/zenlixai--hitl-mcp)

HTML

<a href="/listings/zenlixai--hitl-mcp"><img src="/api/listings/zenlixai--hitl-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone <your-repo-url>
cd hitl-mcp
npm install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 947 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # hitl-mcp
  2. Question-only HITL MCP server for agent workflows.
  3. [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
  4. [![MCP](https://img.shields.io/badge/MCP-Protocol-green.svg)](https://modelcontextprotocol.io/)
  5. [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  6. [English](README.md) | [中文](README-zh.md)
  7. ---
  8. ## Table of Contents
  9. - [Background](#background)
  10. - [What hitl-mcp is](#what-hitl-mcp-is)
  11. - [Goals](#goals)
  12. - [Non-goals](#non-goals)
  13. - [Core model](#core-model)
  14. - [Quick start](#quick-start)
  15. - [How interaction works](#how-interaction-works)
  16. - [MCP tools](#mcp-tools)
  17. - [HTTP API](#http-api)
  18. - [Runtime configuration](#runtime-configuration)
  19. - [How it works internally](#how-it-works-internally)
  20. - [Architecture](#architecture)
  21. - [Operations](#operations)
  22. - [Project structure](#project-structure)
  23. ---
  24. ## Background
  25. In many Agent systems, the Agent eventually reaches a point where it cannot continue autonomously:
  26. - a human must approve or reject a decision
  27. - a human must choose one option from several candidates
  28. - a human must provide missing business input
  29. - a workflow must pause until manual confirmation arrives
  30. Without a dedicated HITL layer, these workflows are usually implemented with ad hoc prompts, side-channel UIs, or custom callback protocols. That creates three recurring problems:
  31. 1. The Agent and the application do not share a stable model for "pending human input".
  32. 2. Human answers are hard to correlate with the exact Agent run and session that requested them.
  33. 3. Waiting, partial submission, cancellation, and recovery semantics become inconsistent across clients.
  34. `hitl-mcp` solves this by exposing a narrow, explicit contract for human questions:
  35. - Agents create questions
  36. - clients or operator UIs read pending questions
  37. - humans answer, skip, or cancel them
  38. - Agents wait on a caller-scoped state machine until work is complete
  39. ---
  40. ## What hitl-mcp is
  41. `hitl-mcp` is a **question-oriented human-in-the-loop server** built on MCP and HTTP.
  42. It provides two access surfaces over the same underlying state:
  43. - **MCP tools** for Agents and Agent platforms
  44. - **HTTP APIs** for operator consoles, backends, or custom approval UIs
  45. The public abstraction is intentionally small:
  46. - the public unit is `question`
  47. - questions belong to a **caller scope**
  48. - answers may be submitted incrementally
  49. - waiting is modeled as a scope-level operation, not a question-level long poll
  50. The server is designed for workflows where the Agent is the initiator, but a human completes part of the decision loop.
  51. ---
  52. ## Goals
  53. - Provide a stable, minimal HITL contract for Agent workflows.
  54. - Make caller isolation explicit through `agent_identity` and `agent_session_id`.
  55. - Support multiple pending questions in the same caller scope.
  56. - Support partial progress instead of forcing an all-at-once final submission.
  57. - Allow MCP and HTTP clients to operate on the same underlying question state.
  58. - Keep storage pluggable so local development can use memory and production can use Redis.
  59. - Keep operational behavior observable through health, readiness, metrics, and structured logs.
  60. ---
  61. ## Non-goals
  62. - Not a generic workflow engine.
  63. - Not a UI framework for approval consoles.
  64. - Not a task queue or event bus.
  65. - Not a general-purpose form builder.
  66. - Not a policy engine for access control and reviewer assignment.
  67. - Not a durable orchestration platform for arbitrary business processes.
  68. `hitl-mcp` only manages question state, caller scoping, waiting semantics, and answer submission.
  69. ---
  70. ## Core model
  71. ### Public unit: question
  72. Externally, the system only exposes `question`.
  73. A question has:
  74. - a server-generated `question_id`
  75. - a `type`
  76. - prompt metadata such as `title`, `description`, `tags`, and `extra`
  77. - for `single_choice`, each option may also declare `followup_fields`
  78. - an optional `default_answer`
  79. - a status such as `pending`, `answered`, `skipped`, or `cancelled`
  80. Supported question types:
  81. - `single_choice`
  82. - `multi_choice`
  83. - `text`
  84. - `boolean`
  85. - `range`
  86. ### Caller scope
  87. Every operation is scoped by:
  88. - `agent_identity`
  89. - `agent_session_id`
  90. This scope is the isolation boundary for:
  91. - creating questions
  92. - listing pending questions
  93. - waiting for progress
  94. - submitting answers
  95. - cancelling questions
  96. Two Agents can ask identical questions without colliding as long as their caller scopes differ.
  97. ### Internal groups vs public API
  98. The storage layer may still use grouping internally, but grouping is an implementation detail.
  99. The public API is intentionally question-first:
  100. - create questions
  101. - fetch pending questions
  102. - submit answers by `question_id`
  103. - cancel by `question_id`
  104. - wait on the scope
  105. ### Partial submission
  106. Answers do not need to arrive in one batch.
  107. The server accepts incremental progress:
  108. - answer one question now
  109. - answer another question later
  110. - skip optional questions explicitly
  111. - continue waiting until the scope becomes complete
  112. Answer payloads remain backward compatible:
  113. - existing callers may continue sending `{ value }`
  114. - when a selected `single_choice` option declares `followup_fields`, callers may send `{ value, fields }`
  115. - required `followup_fields` are validated against the selected option
  116. ### Timeout auto-response
  117. Question groups may also define timeout behavior at creation time.
  118. - callers may set `timeout_seconds`
  119. - if omitted, the server uses `HITL_PENDING_DEFAULT_TIMEOUT_SECONDS`
  120. - each question may set `default_answer`
  121. - if omitted, the server derives one by question type
  122. Timed-out pending questions are automatically answered with their resolved default answers.
  123. - in `memory` mode, this works for single-process deployments via an in-process timeout worker
  124. - in `redis` mode, this works across instances via Redis-backed timeout processing
  125. The derived defaults are:
  126. - `single_choice`: first option value
  127. - `multi_choice`: first option value as a single-element array
  128. - `boolean`: `true`
  129. - `range`: `range_constraints.min`
  130. - `text`: `"none"`
  131. Timeout-generated answers keep the normal `answered` status and add metadata such as:
  132. - `auto_response_at`
  133. - `is_timeout_auto_response`
  134. ### Wait modes
  135. `hitl_wait` and the equivalent scope-level wait behavior support two modes:
  136. - `terminal_only`: return only when the scope has no pending questions left
  137. - `progressive`: return after every state change, then let the caller wait again
  138. `terminal_only` is simpler for linear workflows. `progressive` is better when the caller needs to react to each intermediate update.
  139. When `hitl_wait` is called through MCP, it also emits a progress notification every 30 seconds while the wait is still pending.
  140. ---
  141. ## Quick start
  142. ## Installation
  143. ```bash
  144. git clone <your-repo-url>
  145. cd hitl-mcp
  146. npm install
  147. ```
  148. ## Run in development
  149. ```bash
  150. npm run dev
  151. ```
  152. Default local bind:
  153. - HTTP base URL: `http://0.0.0.0:3000`
  154. - MCP base URL: `http://0.0.0.0:3000/mcp`
  155. - HTTP API prefix: `/api/v1`
  156. ## Run with Docker
  157. Build the image:
  158. ```bash
  159. docker build -t hitl-mcp .
  160. ```
  161. Run with in-memory storage:
  162. ```bash
  163. docker run --rm -p 3000:3000 \
  164. -e MCP_URL=http://localhost:3000 \
  165. hitl-mcp
  166. ```
  167. Run with Redis:
  168. ```bash
  169. docker run --rm -p 3000:3000 \
  170. -e MCP_URL=http://localhost:3000 \
  171. -e HITL_STORAGE=redis \
  172. -e HITL_REDIS_URL=redis://host.docker.internal:6379 \
  173. hitl-mcp
  174. ```
  175. ## Run from source with environment variables
  176. ```bash
  177. export MCP_URL=http://localhost:3000
  178. npm run dev
  179. ```
  180. ## Minimal create request
  181. ```bash
  182. curl -X POST "http://localhost:3000/api/v1/questions" \
  183. -H "Content-Type: application/json" \
  184. -H "x-agent-identity: agent/example" \
  185. -H "x-agent-session-id: session-123" \
  186. -d '{
  187. "title": "Outline confirmation",
  188. "questions": [
  189. {
  190. "type": "single_choice",
  191. "title": "Confirm the current outline",
  192. "options": [
  193. { "value": "approved", "label": "Approved" },
  194. {
  195. "value": "revise",
  196. "label": "Revise",
  197. "followup_fields": [
  198. {
  199. "id": "comment",
  200. "type": "text",
  201. "label": "Revision comment",
  202. "required": true,
  203. "description": "Explain what should change."
  204. }
  205. ]
  206. }
  207. ]
  208. }
  209. ]
  210. }'
  211. ```
  212. ---
  213. ## How interaction works
  214. This section describes the intended runtime flow, regardless of whether the caller uses MCP tools or HTTP APIs.
  215. ### Sequence 1: standard ask -> wait -> answer -> complete
  216. 1. The Agent creates one or more questions in its caller scope.
  217. 2. The Agent immediately calls `hitl_wait`.
  218. 3. A UI or backend fetches pending questions for the same caller scope.
  219. 4. A human answers one or more pending questions.
  220. 5. The Agent waits on the scope.
  221. 6. When the scope has no pending questions left, wait returns a terminal result.
  222. ### Sequence 2: partial submission
  223. 1. The Agent creates multiple questions.
  224. 2. The human answers only a subset.
  225. 3. The server persists those answers and keeps the remaining questions pending.
  226. 4. The Agent can keep waiting.
  227. 5. Additional submissions continue until the scope is complete.
  228. ### Sequence 3: progressive wait
  229. 1. `HITL_WAIT_MODE=progressive`
  230. 2. The Agent calls `hitl_wait`.
  231. 3. Any answer, skip, or cancellation in the scope wakes the waiter.
  232. 4. The wait result reports which `question_id`s changed.
  233. 5. The Agent decides whether to continue waiting or act on the intermediate update.
  234. ### Sequence 4: cancellation
  235. 1. A caller cancels one question or all pending questions in the scope.
  236. 2. The server updates scope state and notifies waiters.
  237. 3. If no pending questions remain, the scope becomes terminal.
  238. ### Sequence 5: timeout auto-response
  239. 1. The Agent creates questions with explicit or implicit timeout behavior.
  240. 2. In Redis mode, the server schedules the pending group for timeout processing.
  241. 3. If no human response arrives before the deadline, a Redis-backed timeout worker auto-answers remaining pending questions.
  242. 4. The worker publishes a scope update so waiters on any instance can wake up.
  243. 5. `hitl_wait` returns the completed scope snapshot with timeout metadata on affected questions.
  244. ### Scope semantics
  245. Wait is always a **scope-level** operation.
  246. This is deliberate:
  247. - one Agent run may have multiple pending questions
  248. - the Agent usually cares whether the workflow can continue
  249. - scope-level wait avoids fragmented per-question synchronization logic
  250. Operational rule:
  251. - after every `hitl_ask`, the next HITL tool call must be `hitl_wait`
  252. - do not treat `hitl_ask` as completion
  253. - do not substitute `hitl_get_pending_questions` for the first post-ask wait
  254. ---
  255. ## MCP tools
  256. `hitl-mcp` exposes the following MCP tools:
  257. ### `hitl_ask`
  258. Creates one or more questions for the current caller scope.
  259. Input shape:
  260. ```json
  261. {
  262. "title": "Release decision",
  263. "description": "Human approval required before deploy",
  264. "ttl_seconds": 3600,
  265. "timeout_seconds": 900,
  266. "questions": [
  267. {
  268. "type": "boolean",
  269. "title": "Approve deployment?",
  270. "default_answer": { "value": true }
  271. }
  272. ]
  273. }
  274. ```
  275. Notes:
  276. - `question_id` must not be provided by the caller
  277. - the server generates `question_id`
  278. - one request can create multiple questions
  279. - explicit `default_answer` is recommended
  280. - if `default_answer` is omitted, the server derives one
  281. - if `timeout_seconds` is omitted, the server uses the configured default timeout
  282. ### `hitl_wait`
  283. Waits on the current caller scope.
  284. Typical response fields:
  285. - `status`
  286. - `is_terminal`
  287. - `changed_question_ids`
  288. - `pending_questions`
  289. - `resolved_questions`
  290. - `answered_question_ids`
  291. - `skipped_question_ids`
  292. - `cancelled_question_ids`
  293. - `is_complete`
  294. `resolved_questions` contains the full resolved question objects plus their final status and any stored answer.
  295. When a result was produced by timeout automation, the resolved question may also include:
  296. - `auto_response_at`
  297. - `is_timeout_auto_response`
  298. When called over MCP, `hitl_wait` also sends `notifications/progress` updates every 30 seconds while still waiting.
  299. ### `hitl_get_pending_questions`
  300. Returns all pending questions in the current caller scope.
  301. ### `hitl_submit_answers`
  302. Submits new answers and optional skips.
  303. Input shape:
  304. ```json
  305. {
  306. "answers": {
  307. "q_01JXYZ...": { "value": true }
  308. },
  309. "skipped_question_ids": ["q_01JABC..."],
  310. "idempotency_key": "idem-1"
  311. }
  312. ```
  313. Notes:
  314. - `answers` may contain any subset of pending questions
  315. - optional questions may be skipped explicitly
  316. - required questions cannot be skipped
  317. - submissions accumulate server-side
  318. ### `hitl_cancel_questions`
  319. Cancels selected pending questions or all pending questions in the scope.
  320. Input shape:
  321. ```json
  322. {
  323. "question_ids": ["q_01JXYZ..."],
  324. "reason": "no longer needed"
  325. }
  326. ```
  327. Or:
  328. ```json
  329. {
  330. "cancel_all": true
  331. }
  332. ```
  333. ### `hitl_get_question`
  334. Fetches one question by `question_id`.
  335. ---
  336. ## HTTP API
  337. The HTTP control plane is primarily for operator UIs, backend services, and troubleshooting.
  338. ### Response envelope
  339. All HTTP responses use the same envelope:
  340. ```json
  341. {
  342. "request_id": "http-request-id",
  343. "success": true,
  344. "data": {},
  345. "error": null
  346. }
  347. ```
  348. On failure:
  349. ```json
  350. {
  351. "request_id": "http-request-id",
  352. "success": false,
  353. "data": {},
  354. "error": {
  355. "code": "QUESTION_NOT_FOUND",
  356. "message": "question not found",
  357. "details": null
  358. }
  359. }
  360. ```
  361. ### Headers and identity rules
  362. For question APIs, the server requires a session header on every caller-scoped request:
  363. - default session header: `x-agent-session-id`
  364. Identity rules:
  365. - send `x-agent-identity` on every caller-scoped request
  366. Operationally:
  367. - the server reads `agent_identity` directly from `x-agent-identity`
  368. ### `GET /api/v1/healthz`
  369. Returns liveness status.
  370. ### `GET /api/v1/readyz`
  371. Returns readiness status.
  372. This is the correct probe for Redis-backed production deployments.
  373. ### `GET /api/v1/metrics`
  374. Returns an in-process metrics snapshot.
  375. ### `POST /api/v1/questions`
  376. Creates one or more questions for the current caller scope.
  377. Request body:
  378. ```json
  379. {
  380. "title": "Release decision",
  381. "description": "Human approval required before deploy",
  382. "ttl_seconds": 3600,
  383. "timeout_seconds": 900,
  384. "questions": [
  385. {
  386. "type": "single_choice",
  387. "title": "Confirm the current outline",
  388. "options": [
  389. { "value": "approved", "label": "Approved" },
  390. {
  391. "value": "revise",
  392. "label": "Revise",
  393. "followup_fields": [
  394. {
  395. "id": "comment",
  396. "type": "text",
  397. "label": "Revision comment",
  398. "required": true,
  399. "description": "Explain what should change."
  400. }
  401. ]
  402. }
  403. ],
  404. "default_answer": { "value": "approved" }
  405. },
  406. {
  407. "type": "text",
  408. "title": "Anything to note?",
  409. "required": false,
  410. "default_answer": { "value": "none" }
  411. }
  412. ]
  413. }
  414. ```
  415. Supported question payloads:
  416. - `single_choice` with `options`
  417. - `single_choice.options[].followup_fields` for option-specific text follow-up inputs
  418. - `multi_choice` with `options`
  419. - `text` with optional `text_constraints`
  420. - `boolean`
  421. - `range` with `range_constraints`
  422. Additional create-time fields:
  423. - `timeout_seconds`: optional positive integer timeout for the group
  424. - `default_answer`: optional per-question fallback answer used by Redis timeout auto-response
  425. ### `GET /api/v1/questions/pending`
  426. Returns all pending questions for the current caller scope.
  427. ### `POST /api/v1/questions/answers`
  428. Submits answered and skipped questions.
  429. Request body:
  430. ```json
  431. {
  432. "answers": {
  433. "q_01JXYZ...": {
  434. "value": "revise",
  435. "fields": {
  436. "comment": "Please add recovery conditions."
  437. }
  438. }
  439. },
  440. "skipped_question_ids": ["q_01JABC..."],
  441. "idempotency_key": "idem-1"
  442. }
  443. ```
  444. Behavior:
  445. - accepts partial progress
  446. - persists cumulative scope state
  447. - wakes scope waiters after successful submission
  448. - continues to accept plain `{ value }` answers when no follow-up fields are required
  449. Typical error codes:
  450. - `QUESTION_NOT_FOUND`
  451. - `ANSWER_VALIDATION_FAILED`
  452. ### `POST /api/v1/questions/cancel`
  453. Cancels pending questions in the current caller scope.
  454. Request body:
  455. ```json
  456. {
  457. "question_ids": ["q_01JXYZ..."],
  458. "reason": "no longer needed"
  459. }
  460. ```
  461. Or:
  462. ```json
  463. {
  464. "cancel_all": true
  465. }
  466. ```
  467. ### `GET /api/v1/questions/:question_id`
  468. Fetches one question by `question_id`.
  469. If the question does not exist, the server returns `404` with `QUESTION_NOT_FOUND`.
  470. ---
  471. ## Runtime configuration
  472. ## Configuration sources and precedence
  473. Configuration is loaded in this order:
  474. 1. built-in defaults
  475. 2. `config/hitl-mcp.yaml`
  476. 3. `.env`
  477. 4. process environment variables
  478. Later sources override earlier ones.
  479. ## Environment variables
  480. The following environment variables are currently supported by the codebase.
  481. | Variable | Default | Purpose | When to change |
  482. | --- | --- | --- | --- |
  483. | `PORT` | `3000` | Fallback HTTP port. Equivalent to `HITL_HTTP_PORT` when set. | Change when your runtime injects only `PORT` or when a platform requires a fixed port env. |
  484. | `MCP_URL` | `http://0.0.0.0:3000` | Public base URL used by the MCP server metadata. | Change in any non-local deployment so MCP clients receive the reachable external URL. |
  485. | `HITL_SERVER_NAME` | `hitl-mcp` | MCP server name metadata. | Change when embedding this server under another product identity. |
  486. | `HITL_SERVER_VERSION` | `0.1.0` | MCP server version metadata. | Change when publishing a packaged build with an explicit runtime version. |
  487. | `HITL_HTTP_HOST` | `0.0.0.0` | HTTP bind host. | Change only if you intentionally want loopback-only binding or a different interface. |
  488. | `HITL_HTTP_PORT` | `3000` | Explicit HTTP port. Overrides the default port. | Change in local multi-service setups or production platforms with custom port mapping. |
  489. | `HITL_HTTP_API_PREFIX` | `/api/v1` | Prefix for HTTP control-plane routes. | Change only if you need to mount the API behind a different path segment. |
  490. | `HITL_STORAGE` | `memory` | Storage backend selection: `memory` or `redis`. | Set to `redis` for multi-process or durable deployments. |
  491. | `HITL_REDIS_URL` | `redis://127.0.0.1:6379` | Redis connection URL. | Required when `HITL_STORAGE=redis` outside local defaults. |
  492. | `HITL_REDIS_PREFIX` | `hitl` | Redis key prefix. | Change when multiple environments share one Redis instance. |
  493. | `HITL_TTL_SECONDS` | `604800` | Default TTL for newly created question sets. | Change to align pending-question retention with your business SLA. |
  494. | `HITL_ANSWERED_RETENTION_SECONDS` | `2592000` | Retention window for answered state. | Change when auditability or storage pressure requires a different retention period. |
  495. | `HITL_PENDING_MAX_WAIT_SECONDS` | `0` | Maximum duration for one wait call. `0` means no timeout limit. | Change when you need bounded waits for worker scheduling or request lifecycle control. |
  496. | `HITL_WAIT_MODE` | `terminal_only` | Scope wait behavior: `terminal_only` or `progressive`. | Set to `progressive` when callers must react to each intermediate update. |
  497. | `HITL_PENDING_DEFAULT_TIMEOUT_SECONDS` | `900` | Default timeout for newly created pending question groups when `timeout_seconds` is omitted. | Change when human response SLAs differ across environments. |
  498. | `HITL_PENDING_TIMEOUT_POLL_INTERVAL_SECONDS` | `5` | Polling interval for the Redis timeout worker. Small drift from the exact timeout boundary is acceptable. | Change when you want tighter or looser timeout-trigger granularity. |
  499. | `HITL_AGENT_SESSION_HEADER` | `x-agent-session-id` | Header name used to read `agent_session_id`. | Change when integrating with an existing gateway or client that uses another session header. |
  500. | `HITL_CREATE_CONFLICT_POLICY` | `error` | Create conflict policy in config surface. | Keep at default. The current code validates and loads it, but it is not currently applied by request handlers. |
  501. | `HITL_LOG_LEVEL` | `info` | Structured logging level: `debug`, `info`, `warn`, `error`. | Raise or lower verbosity to match debugging and production noise requirements. |
  502. | `HITL_ENABLE_METRICS` | `true` | Enables metrics collection in config. | Leave enabled unless you are intentionally minimizing observability overhead. |
  503. ## YAML example
  504. ```yaml
  505. http:
  506. host: 0.0.0.0
  507. port: 3000
  508. apiPrefix: /api/v1
  509. storage:
  510. kind: redis
  511. redis:
  512. url: redis://127.0.0.1:6379
  513. keyPrefix: hitl
  514. ttl:
  515. defaultSeconds: 604800
  516. answeredRetentionSeconds: 2592000
  517. pending:
  518. maxWaitSeconds: 0
  519. waitMode: terminal_only
  520. defaultTimeoutSeconds: 900
  521. timeoutPollIntervalSeconds: 5
  522. agentIdentity:
  523. sessionHeader: x-agent-session-id
  524. createConflictPolicy: error
  525. observability:
  526. logLevel: info
  527. enableMetrics: true
  528. ```
  529. ## Configuration recommendations
  530. ### Local development
  531. - `HITL_STORAGE=memory`
  532. - send `x-agent-identity` from your client or test harness
  533. - keep `HITL_WAIT_MODE=terminal_only`
  534. - timeout auto-response is available in single-process memory mode
  535. ### Shared dev or staging
  536. - `HITL_STORAGE=redis`
  537. - set a real `MCP_URL`
  538. - use a distinct `HITL_REDIS_PREFIX`
  539. - review `HITL_PENDING_DEFAULT_TIMEOUT_SECONDS`
  540. - ensure upstream callers always provide `x-agent-identity`
  541. ### Production
  542. - `HITL_STORAGE=redis`
  543. - set `MCP_URL` to the externally reachable URL
  544. - wire readiness to `/api/v1/readyz`
  545. - review TTL and retention values explicitly
  546. - review timeout and polling values explicitly
  547. - ensure upstream callers always provide `x-agent-identity`
  548. ---
  549. ## How it works internally
  550. ### Scope state machine
  551. `hitl-mcp` maintains question progress at the caller-scope level.
  552. Each state-changing operation updates a scope snapshot containing:
  553. - pending questions
  554. - resolved questions with full question payloads and answers when available
  555. - answered question IDs
  556. - skipped question IDs
  557. - cancelled question IDs
  558. - changed question IDs
  559. - completion status
  560. This snapshot is the source of truth for wait results.
  561. ### Waiter notification model
  562. The server keeps an in-process waiter registry keyed by caller scope.
  563. When answers or cancellations arrive:
  564. 1. storage is updated
  565. 2. a fresh scope snapshot is computed
  566. 3. the waiter for that scope is notified
  567. 4. `hitl_wait` resolves according to the configured wait mode
  568. In Redis mode, timeout auto-response also produces waiter notifications. The timeout worker publishes scope updates through Redis pub/sub so a waiter blocked on one instance can still wake up when another instance performs the auto-response.
  569. In memory mode, timeout auto-response produces waiter notifications through the same in-process `Waiter` used for answer and cancellation events.
  570. ### Storage selection
  571. Two storage modes exist:
  572. - **memory**: simple, process-local, good for tests and local development
  573. - **redis**: durable across processes and suitable for real deployments
  574. Both modes enable timeout auto-response, but with different scope:
  575. - **memory**: single-process timeout worker and direct waiter notifications
  576. - **redis**: cross-instance timeout scheduling and distributed wakeups
  577. Redis mode additionally uses:
  578. - a Redis sorted set for due-time scheduling
  579. - short-lived distributed locks to avoid double-processing in multi-instance deployments
  580. - Redis pub/sub to notify waiters across instances
  581. If Redis is selected but unavailable during runtime initialization, the server falls back to in-memory storage and logs a warning.
  582. That fallback is useful in local development, but production environments should treat it as a misconfiguration signal.
  583. ### Identity handling
  584. For HTTP question APIs:
  585. - session identity comes from `HITL_AGENT_SESSION_HEADER`
  586. - caller identity comes from `x-agent-identity`
  587. For MCP tool calls:
  588. - the server injects caller scope into MCP tool state from request context
  589. - the tool layer reads `agent_identity` and `agent_session_id` from that injected state
  590. ---
  591. ## Architecture
  592. The runtime has five main layers.
  593. ### 1. Config layer
  594. Loads and validates configuration from defaults, YAML, `.env`, and runtime environment variables.
  595. ### 2. Server layer
  596. Builds the MCP server and the HTTP app, attaches middleware, and registers routes and tools.
  597. ### 3. Service layer
  598. `HitlService` defines the operational behavior for:
  599. - create
  600. - list pending
  601. - wait
  602. - submit answers
  603. - cancel
  604. - fetch question
  605. This is the main application boundary.
  606. ### 4. Storage layer
  607. Provides repository implementations for:
  608. - in-memory development and tests
  609. - Redis-backed persistence
  610. The Redis implementation also owns timeout scheduling, distributed lock acquisition, and timeout-driven default-answer persistence.
  611. ### 5. Observability layer
  612. Provides:
  613. - structured logs
  614. - request IDs
  615. - readiness checks
  616. - metrics snapshots
  617. ### Request flow summary
  618. For HTTP:
  619. 1. caller context middleware resolves identity and session
  620. 2. route handler validates input and calls `HitlService`
  621. 3. repository updates state
  622. 4. response is wrapped in the standard envelope
  623. For MCP:
  624. 1. MCP request context is inspected
  625. 2. caller scope is injected into tool state
  626. 3. tool handler delegates to `HitlService`
  627. 4. tool output reflects the latest scope state
  628. ---
  629. ## Operations
  630. ## Health and readiness
  631. - Liveness: `GET /api/v1/healthz`
  632. - Readiness: `GET /api/v1/readyz`
  633. - Metrics: `GET /api/v1/metrics`
  634. Use readiness, not liveness, to guard Redis-backed production traffic.
  635. ## Logging
  636. The server emits structured request and error logs.
  637. Set `HITL_LOG_LEVEL=debug` when troubleshooting request flow or repository behavior.
  638. ## Metrics
  639. Metrics are exposed as a JSON snapshot through `/api/v1/metrics`.
  640. The current implementation tracks operational signals such as wait duration and pending counts.
  641. ## Common deployment checks
  642. Before declaring a deployment healthy, verify:
  643. 1. `MCP_URL` matches the externally reachable URL.
  644. 2. The exposed HTTP port matches your runtime or ingress mapping.
  645. 3. `HITL_STORAGE=redis` is paired with a reachable Redis instance.
  646. 4. Upstream callers send `x-agent-identity` and the configured session header.
  647. 5. `/api/v1/healthz`, `/api/v1/readyz`, and `/api/v1/metrics` all respond as expected.
  648. ---
  649. ## Project structure
  650. ```text
  651. .
  652. ├── config/ # YAML configuration examples
  653. ├── docs/
  654. │ ├── api/ # MCP tool and HTTP API reference docs
  655. │ └── runbooks/ # Operational runbooks
  656. ├── src/
  657. │ ├── config/ # Config schema, defaults, loaders
  658. │ ├── core/ # HitlService application logic
  659. │ ├── domain/ # Domain types, schemas, validators
  660. │ ├── http/ # Hono routes, middleware, response helpers
  661. │ ├── mcp/ # MCP tool registration and caller-scope helpers
  662. │ ├── observability/ # Logging and metrics
  663. │ ├── state/ # Waiter and state-machine helpers
  664. │ └── storage/ # In-memory and Redis repositories
  665. ├── tests/ # Unit and integration coverage
  666. ├── Dockerfile # Production-oriented container build
  667. └── index.ts # Runtime entrypoint
  668. ```
  669. ## Related docs
  670. - [MCP tools](docs/api/mcp-tools.md)
  671. - [HTTP API](docs/api/http-openapi.md)
  672. - [Production runbook](docs/runbooks/production.md)
  673. - [HITL skill](skills/hitl/SKILL.md)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.