Haptique OS Docs

Appearance

AI Driver Builder MCP ​

The AI Driver Builder MCP server lives at apps/mcp-driver-builder. It gives AI assistants a constrained way to generate reviewable Haptique OS local driver packages from a plain-language device description.

This is an OS-local workflow. It uploads through the HOS Integration Manager package path and does not replace Fleet cloud integrations or legacy /integration/... routes.

The legacy product entry point remains /os/driver-integrations/ai-builder. The primary broader surface is now OS Builder Chat under AI Chat Development Mode. HOS acts as the MCP host, connects to the local stdio Driver Builder MCP server, and lets the selected AI provider call driver-builder tools through the HOS-owned agent loop. Supported in-OS inference providers are Local, OpenRouter, and Gemini API.

Important service boundary:

  • apps/mcp-driver-builder owns driver schema, generation, validation, packaging, artifact versioning, and controlled driver-doc research.
  • apps/mcp-service is the general OS MCP service used by the OS Builder Chat agent to call HOS tools and APIs.
  • apps/llama-service is the older OS AI runtime compatibility path.
  • Gemini is a model/provider backend only in v1. HOS does not expose Gemini CLI shell/file tools to end users.

Runtime Targets ​

RuntimeUpload fileStatus
javascript.jsFirst-class local driver runtime. Uses Node-compatible CommonJS and newline-delimited JSON over stdin/stdout.
python.pyLocal driver runtime using the same JSON-line process contract.
lua.luaLocal command-oriented driver runtime.
typescriptcompiled .jsAuthoring/generation option only. Raw .ts is not accepted in OS driver ZIP uploads for v1.

JavaScript drivers use the HOS-managed JavaScriptDriverProcess. It starts Node with a configurable binary (HOS_NODE_BINARY or process.execPath), forwards stderr, parses stdout JSON lines, writes commands to stdin, and terminates with SIGTERM before SIGKILL fallback.

Generated Package Contract ​

A valid generated package contains:

  • Exactly one *.driver.json manifest.
  • Exactly one .py, .lua, or .js driver implementation.
  • Optional README.md.
  • Optional package.json only when a JavaScript driver needs external dependencies.

For JavaScript v1, dependency-free packages are preferred. Generated JS drivers should use Node 20+ built-ins such as fetch, net, dgram, and readline where possible.

Manifest Requirements ​

The manifest drives the Integration Manager listing, setup form, logical-device UI, command catalog, and runtime launch.

Required behavior:

  • driverType must be python, lua, or javascript for local uploaded drivers.
  • driverFile must point to the matching implementation file.
  • properties define the Integration Manager setup form.
  • commands define user-visible actions and command payload schemas.
  • io defines integration inputs/outputs for UI and topology display.
  • envMap maps setup properties into runtime environment variables.

Driver Protocol Requirements ​

Generated local drivers must emit and handle the same core protocol concepts as remote WebSocket drivers:

DirectionMessageRequired behavior
Driver to HOSDEVICE_DISCOVEREDCreate or refresh logical devices.
Driver to HOSSTATE_UPDATEPublish current runtime state.
Driver to HOSACTION_RESULTReport command success/failure.
Driver to HOSMETRIC_UPDATEOptional telemetry.
HOS to driverACTIONExecute a user or automation command.
HOS to driverCOMMAND_EXECUTEExecute command-catalog driven actions.

Generated JavaScript templates support HTTP, TCP, UDP, WebSocket-device, and generic polling patterns. They should keep credentials in environment variables or setup properties, never hard-code secrets.

MCP Tool Workflow ​

The MCP app exposes tools that let an AI assistant:

  1. Read HOS driver context and schema rules.
  2. Find similar reference drivers.
  3. Draft an implementation plan from device documentation.
  4. Generate a manifest.
  5. Generate driver code.
  6. Validate the manifest and code.
  7. Build an uploadable ZIP package.
  8. Hand off upload instructions for the HOS Integration Manager.

The upload route remains the existing Integration Manager validation path. Direct MCP upload should only be added if it reuses that same validation and auth model.

In-OS Chat Flow ​

The in-OS user flow is:

  1. Open Integration Manager.
  2. Click AI Driver Builder.
  3. Ensure AI Settings has Local, OpenRouter, or Gemini configured and the AI service is running.
  4. Pick the model from the composer footer when a different Driver Builder model is needed.
  5. Describe the device, protocol, API endpoints, auth, and desired commands.
  6. The selected provider calls driver_builder_* tools through HOS.
  7. HOS calls the MCP server and saves generated ZIP output as an artifact under storage/ai/driver-builder/.
  8. The UI shows downloadable artifacts for review and Integration Manager upload.

This keeps MCP local to the OS process while allowing the model itself to be local, OpenRouter-backed, or Gemini-backed. Users do not need Claude Desktop, Gemini CLI, ChatGPT developer mode, or manual MCP configuration for the main product flow.

OS Builder Chat can also route driver requests through managed AgentTask state:

  1. User starts a Development Mode prompt.
  2. HOS creates an OS Builder task with intent, plan, steps, activity, artifacts, and approval requests.
  3. Read-only tool calls and driver package generation can run automatically.
  4. Installing packages or changing OS configuration requires preview plus approval.
  5. Generated driver artifacts remain available for review, tagging, revision, and Integration Manager upload.

OpenRouter generation uses OPENROUTER_TIMEOUT_MS, defaulting to 120000 ms, because driver-building prompts can take substantially longer than ordinary chat completions.

The Driver Builder agent loop uses AI_DRIVER_BUILDER_MAX_TOOL_ITERATIONS, defaulting to 12. Successful driver_builder_generate_package calls are terminal: the agent returns the generated artifact summary immediately instead of spending extra model steps summarizing.

The OS controller waits up to AI_DRIVER_BUILDER_SYNC_TIMEOUT_MS, defaulting to 300000 ms, for in-OS chat generation to finish.

Controlled Internet Sources ​

Driver Builder can use internet sources for device API exploration, but only after the user approves the chat-time prompt in AI Builder.

Allowed sources:

  • Vendor documentation and manuals.
  • Public API/reference/developer docs.
  • GitHub examples and public driver samples.
  • Public documentation pages relevant to driver implementation.

Blocked or rejected sources:

  • localhost, private LAN IPs, link-local addresses, and loopback URLs.
  • URLs containing embedded credentials.
  • Non-HTTP protocols.
  • General web pages that do not look like documentation, API, support, wiki, reference, integration, or GitHub example pages.

The permission is short-lived and scoped to the Driver Builder request. The model must include source URLs in the AI Builder chat when those sources influence generated code. Generated packages remain reviewable artifacts and are not installed automatically.

Using the AI Driver Builder ​

The AI Driver Builder is available inside Haptique OS under Integration Manager → AI Driver Builder. No CLI setup is required — the MCP server runs as part of the OS process.

To use it:

  1. Open Integration Manager in the HOS admin UI
  2. Click AI Driver Builder
  3. Ensure AI Settings has Local, OpenRouter, or Gemini configured
  4. Describe your device, protocol, API endpoints, auth method, and desired commands
  5. The AI generates a complete driver package (manifest + implementation)
  6. Download the artifact and upload it through Integration Manager

Cross-References ​