HIT-1.0 SDK

Hierarchical Intent Tree � The UI Protocol for AI Agents

The HIT SDK enables your web application to publish a structured, machine-readable contract of its UI capabilities � so AI Agents can navigate and operate it deterministically, without pixel-scraping or fragile CSS selectors.

Files

| File | Purpose | |------|---------| | hit-core.js | Framework-agnostic core engine | | hit-react.js | React hooks, HOC, and components | | hit-server.js | In-browser HIT-Manager server simulation |

Quick Start

1. Include the script

<script src="hit-core.js"></script>

2. Register a node

HIT.register('checkout.submit_btn', {
  role: 'action',
  intent: { domain: 'commerce', action: 'submit', object: 'order', context: 'checkout_flow' },
  metadata: { label: 'Complete Purchase', description: 'Finalizes the transaction.' },
  actions: [
    {
      name: 'execute',
      params: { payment_method: 'string', confirm_total: 'number' },
      returns: 'order_id',
      risk: 'high',
      handler: async ({ payment_method, confirm_total }) => {
        // Your submit logic here
        return { order_id: 'ORD_12345' };
      }
    }
  ]
}, document.getElementById('submit-btn'));

3. Query the tree (as an Agent)

const tree = HIT.AgentPortal.get_tree();
console.log(tree);

4. Execute an intent

const result = await HIT.AgentPortal.execute_intent('commerce.submit.order', {
  payment_method: 'card_visa',
  confirm_total: 99.99
});

Core API

HIT.Manager

| Method | Description | |--------|-------------| | register(config) | Register a UI node | | deregister(uid) | Remove a node | | getTree() | Get full nested DIL tree | | getNode(uid) | Get single node schema | | patchState(uid, update) | Update node state + emit event | | focusNode(uid) | Signal agent focus (Ghost Highlight) | | callAction(uid, name, params) | Execute an action | | subscribe(event, cb) | Subscribe to events |

HIT.AgentPortal (MCP Interface)

| Method | Description | |--------|-------------| | list_nodes(filter?) | List nodes with optional filter | | inspect_node(uid) | Full schema for a node | | execute_intent(goal, params) | Map high-level goal ? action | | subscribe_events(cb) | Stream all state changes | | get_tree() | Returns full tree |

HIT.KillSwitch

HIT.kill('User requested stop');  // Freeze all HIT operations
HIT.resume();                      // Release the kill switch

HIT.Guardrail

High-risk actions (risk: 'high') automatically emit guardrail:pending before executing:

HIT.EventBus.on('guardrail:pending', ({ confirm, reject, label, action }) => {
  if (window.confirm(`Confirm high-risk action: ${label} ? ${action}?`)) {
    confirm();
  } else {
    reject();
  }
});

Events

| Event | Payload | |-------|---------| | manager:registered | { uid, node } | | manager:deregistered | { uid } | | PATCH_STATE | { uid, previousState, newState, timestamp } | | PATCH_STATE:{uid} | Same as above, uid-scoped | | focus:node | { uid, node, timestamp } | | action:called | { uid, action, params, timestamp } | | action:success | { uid, action, result, timestamp } | | action:error | { uid, action, error, timestamp } | | guardrail:pending | { uid, label, action, params, risk, confirm, reject } | | guardrail:confirmed | { uid } | | guardrail:rejected | { uid } | | killswitch:engaged | { reason, timestamp } | | killswitch:released | { timestamp } |

React Adapter

import { HitProvider, useHitNode, HitKillSwitch, HitGuardrailPrompt } from './hit-react.js';

function App() {
  return (
    <HitProvider>
      <MyApp />
      <HitKillSwitch />
      <HitGuardrailPrompt />
    </HitProvider>
  );
}

function SubmitButton() {
  const ref = useRef(null);
  const { node, callAction } = useHitNode('checkout.submit_btn', {
    role: 'action',
    intent: { domain: 'commerce', action: 'submit', object: 'order' },
    metadata: { label: 'Complete Purchase' },
    actions: [{ name: 'execute', risk: 'high', handler: async (p) => ({ ok: true }) }]
  }, ref);

  return (
    <button ref={ref} onClick={() => callAction('execute', { confirm_total: 99 })}>
      {node?.metadata.label}
    </button>
  );
}

Node Schema Reference

{
  "hit_version": "1.0",
  "uid": "unique.node.id",
  "role": "action | input | navigation | container | view",
  "intent": {
    "domain": "commerce | productivity | navigation | general | ...",
    "action": "submit | create | delete | navigate | read | update",
    "object": "order | task | user | page | item | ...",
    "context": "optional_flow_context"
  },
  "hierarchy": { "parent_id": null, "children": [] },
  "state": {
    "status": "idle | busy | success | error",
    "enabled": true,
    "visible": true,
    "value": null,
    "errors": []
  },
  "actions": [
    {
      "name": "execute",
      "params": { "param_name": "type" },
      "returns": "return_type",
      "risk": "low | medium | high",
      "handler": "Function (optional, for in-app registration)"
    }
  ],
  "metadata": {
    "label": "Human-readable label",
    "description": "What this node does",
    "bounds": { "x": 0, "y": 0, "w": 120, "h": 40 }
  }
}

Roadmap

• v1.0-Alpha � React/Vue components that auto-register with the HIT-Manager ?
• v1.0-Beta � Standardized WebSocket protocol for Ghost Highlights
• v1.0-Final � Formalizing the domain/action/object vocabulary for cross-app compatibility

MIT License � HIT Protocol Contributors