Merge pull request #18 from Helixar-AI/codex/hdp-physical-readme

docs: add hdp-physical README coverage and tighten CI permissions

Author: asiridalugoda

.github/workflows/ci.yml

@@ -9,6 +9,9 @@ on:
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
+permissions:
+  contents: read
+
 jobs:
   test:
     name: Test

README.md

@@ -50,6 +50,8 @@ When a person authorizes an AI agent to act — and that agent delegates to anot
 | ------------------------------------------------------ | ------------------------------------------------------------ | ---------- | --------------------- | -------------------------------------------------------------------------- |
 | [`@helixar_ai/hdp`](./src)                             | [npm](https://www.npmjs.com/package/@helixar_ai/hdp)         | TypeScript | Any                   | Core SDK — issue, extend, verify HDP tokens                                |
 | [`@helixar_ai/hdp-mcp`](./packages/hdp-mcp)            | [npm](https://www.npmjs.com/package/@helixar_ai/hdp-mcp)     | TypeScript | MCP                   | MCP middleware — attaches HDP to any MCP server                            |
+| [`@helixar_ai/hdp-physical`](./packages/hdp-physical)  | [npm](https://www.npmjs.com/package/@helixar_ai/hdp-physical) | TypeScript | Physical AI / Robotics | HDP-P guardrails — signs EDTs and blocks unsafe robot actions pre-execution |
+| [`hdp-physical`](./packages/hdp-physical-py)           | [PyPI](https://pypi.org/project/hdp-physical/)               | Python     | Physical AI / Robotics | HDP-P guardrails — Python SDK for EDT issuance and pre-execution checks     |
 | [`hdp-crewai`](./packages/hdp-crewai)                  | [PyPI](https://pypi.org/project/hdp-crewai/)                 | Python     | CrewAI                | CrewAI middleware — attaches HDP to any crew                               |
 | [`hdp-grok`](./packages/hdp-grok)                      | [PyPI](https://pypi.org/project/hdp-grok/)                   | Python     | Grok / xAI            | Grok middleware — attaches HDP to any xAI conversation                     |
 | [`hdp-autogen`](./packages/hdp-autogen)                | [PyPI](https://pypi.org/project/hdp-autogen/)                | Python     | AutoGen               | AutoGen middleware — attaches HDP to any AutoGen agent or GroupChat        |
@@ -64,12 +66,24 @@ When a person authorizes an AI agent to act — and that agent delegates to anot
 npm install @helixar_ai/hdp
 ```
 
+**TypeScript / Physical AI**
+
+```bash
+npm install @helixar_ai/hdp-physical
+```
+
 **Python / CrewAI**
 
 ```bash
 pip install hdp-crewai
 ```
 
+**Python / Physical AI**
+
+```bash
+pip install hdp-physical
+```
+
 **Python / Grok (xAI API)**
 
 ```bash
@@ -161,6 +175,73 @@ console.log(token.chain.length); // 2
 
 ---
 
+## Physical AI Integration
+
+`@helixar_ai/hdp-physical` and `hdp-physical` extend HDP into robotics with Embodied Delegation Tokens (EDTs) and a pre-execution guard. Before a motion command reaches an actuator, HDP-P verifies the EDT signature, checks the irreversibility ceiling, enforces excluded zones, and blocks actions that exceed force or velocity limits.
+
+```typescript
+import {
+  EdtBuilder,
+  IrreversibilityClass,
+  PreExecutionGuard,
+  signEdt,
+} from "@helixar_ai/hdp-physical";
+import { generateKeyPair } from "@helixar_ai/hdp";
+
+const { privateKey, publicKey } = await generateKeyPair();
+
+const edt = new EdtBuilder()
+  .setEmbodiment({
+    agent_type: "robot_arm",
+    platform_id: "aloha_v2",
+    workspace_scope: "zone_A",
+  })
+  .setActionScope({
+    permitted_actions: ["pick", "place", "move"],
+    excluded_zones: ["human_zone"],
+    max_force_n: 45,
+    max_velocity_ms: 0.5,
+  })
+  .setIrreversibility({
+    max_class: IrreversibilityClass.REVERSIBLE_WITH_EFFORT,
+    class2_requires_confirmation: true,
+    class3_prohibited: true,
+  })
+  .setPolicyAttestation({
+    policy_hash: "sha256-of-weights",
+    training_run_id: "run-1",
+    sim_validated: true,
+  })
+  .setDelegationScope({
+    allow_fleet_delegation: false,
+    max_delegation_depth: 1,
+    sub_agent_whitelist: [],
+  })
+  .build();
+
+const signedEdt = await signEdt(edt, privateKey, "robot-key-v1");
+const guard = new PreExecutionGuard();
+
+const decision = await guard.authorize(
+  {
+    description: "pick box from left bin",
+    force_n: 5,
+    velocity_ms: 0.2,
+  },
+  signedEdt,
+  publicKey,
+);
+
+console.log(decision.approved);
+```
+
+For Python, install `hdp-physical` and use the same EDT model and guard flow, with optional `lerobot` and `gemma` extras for adapters and interception.
+
+→ [Full TypeScript physical AI docs](./packages/hdp-physical/README.md)
+→ [Full Python physical AI docs](./packages/hdp-physical-py/README.md)
+
+---
+
 ## Grok / xAI Integration
 
 `hdp-grok` attaches HDP to any Grok conversation via three native tool schemas. No changes to your prompts or model configuration are required — Grok calls `hdp_issue_token`, `hdp_extend_chain`, and `hdp_verify_token` as regular tool calls, and `HdpMiddleware` handles everything statelessly behind the scenes.

packages/hdp-physical/README.md

@@ -4,6 +4,9 @@
 
 Part of the [HDP (Human Delegation Provenance)](https://github.com/Helixar-AI/HDP) protocol suite.
 
+This package implements the physical-AI extension of HDP for robots, autonomous vehicles,
+surgical systems, and other embodied agents that can take irreversible actions in the world.
+
 [![npm version](https://img.shields.io/npm/v/@helixar_ai/hdp-physical)](https://www.npmjs.com/package/@helixar_ai/hdp-physical)
 
 ## What it does
@@ -18,6 +21,23 @@ HDP-P wraps physical robot action commands with cryptographic authorization. Bef
 
 An unsigned command from a prompt-injected LLM is caught at step 1 and never reaches the robot.
 
+Unlike purely digital agent workflows, physical actions cannot always be rolled back after the
+fact. HDP-P moves authorization to the pre-execution layer: the guard verifies the delegation
+context before any actuator command is allowed through.
+
+## What the EDT binds
+
+The Embodied Delegation Token (EDT) extends standard HDP delegation with physical-world controls:
+
+- embodiment binding: agent type, platform identifier, and workspace scope
+- action scope: permitted actions, excluded zones, force limits, and velocity ceiling
+- irreversibility ceiling: the highest physical action class the principal authorized
+- policy attestation: hash of the deployed policy weights plus training run metadata
+- delegation scope: whether fleet delegation is allowed and which sub-agents may receive it
+
+This reduces replay across robot fleets, prevents out-of-scope motion plans from executing, and
+helps prove that the policy running on the device is the one the human actually authorized.
+
 ## Install
 
 ```bash
@@ -69,6 +89,23 @@ if (decision.approved) {
 | 2 | `IRREVERSIBLE_NORMALLY` | Press-fit, adhesive bond |
 | 3 | `IRREVERSIBLE_AND_HARMFUL` | Crush, override safety limits |
 
+## Threat model highlights
+
+HDP-P is designed to block several physical-AI failure modes that ordinary network or robot
+identity controls do not solve on their own:
+
+- prompt injection into an orchestration pipeline that generates unauthorized actuator commands
+- unauthorized delegation from one robot or controller to another reachable system in the fleet
+- sim-to-real policy tampering, where deployed weights diverge from the validated model
+- attacks that exploit irreversibility by causing harm before a post-hoc audit can react
+
+## Companion spec
+
+For the full protocol background, threat model, and companion specification:
+
+- [HDP-P Helixar Labs overview](https://deploy-preview-60--helixar.netlify.app/about/labs/hdp-physical/)
+- [Zenodo DOI 10.5281/zenodo.19332440](https://doi.org/10.5281/zenodo.19332440)
+
 ## Live demo
 
 🤖 [HDP-P Physical Safety — Powered by Gemma 4](https://huggingface.co/spaces/helixar-ai/hdp-physical-demo) on HuggingFace